program-notebook

Codex、OpenCode、Kimi Code 与 Pi 的 Program Notebook 插件、skill 和检查工具包。

这个仓库把项目中枢文档约定固定下来：docs/program-notebook.md 是入口索引和状态摘要，docs/architecture/*.md 是结构、数据流、CI、代码风格等专题展开层。检查工具保持只读；skill 被调用后，由 Agent 基于源码证据创建或更新文档。

让 Agent 安装

Codex

把下面这段复制给你的 agent：

Fetch and follow instructions from https://raw.githubusercontent.com/LycanW/program-notebook/refs/heads/main/.codex/INSTALL.md

OpenCode

把下面这段复制给你的 agent：

Fetch and follow instructions from https://raw.githubusercontent.com/LycanW/program-notebook/refs/heads/main/.opencode/INSTALL.md

Kimi Code

把下面这段复制给你的 agent：

Fetch and follow instructions from https://raw.githubusercontent.com/LycanW/program-notebook/refs/heads/main/.kimi/INSTALL.md

Pi

直接安装 npm 上的 Pi package：

pi install npm:program-notebook

重新启动 Pi 或运行 /reload 后，check_notebook 工具、/check-notebook 命令和 program-notebook skill 会生效。

包含内容

• .codex-plugin/plugin.json：Codex plugin 清单。
• .agents/plugins/marketplace.json：Codex marketplace 清单，通过 npm 分发 plugin。
• .mcp.json：Codex 的 check_notebook MCP server 配置。
• .codex/INSTALL.md：Codex 安装说明。
• .opencode/plugins/program-notebook.ts：OpenCode 插件入口。
• extensions/program-notebook.ts：Pi extension，注册 check_notebook 工具和 /check-notebook 命令。
• .opencode/commands/check-notebook.md：OpenCode /check-notebook 命令模板。
• .opencode/INSTALL.md：OpenCode 安装说明。
• kimi.plugin.json：Kimi Code plugin 清单，指向共享 skill。
• .kimi/INSTALL.md：Kimi Code 安装说明。
• bin/check-notebook.ts：命令行检查源码入口。
• bin/check-notebook-mcp.ts：MCP server 源码入口。
• dist/*.mjs：随包发布、由 Node.js 直接运行的 CLI 与 MCP bundle，不要求用户安装 Bun。
• lib/program-notebook-lib.ts：可测试的文档检查逻辑。
• skills/program-notebook/SKILL.md：四个平台共用的精简 skill 入口。
• skills/program-notebook/references/：仅在创建或维护文档时按需读取的详细规范。
• skills/program-notebook/agents/openai.yaml：Codex skill 的 UI 与 MCP 依赖元数据。
• tests/program-notebook-lib.test.ts：核心库测试。
• tests/check-notebook-cli.test.ts：Node.js CLI bundle 测试。

功能

• 为 Codex、OpenCode、Kimi Code 和 Pi 提供同一套 program-notebook skill。
• 暴露只读 check_notebook 工具，检查固定文档路径、architecture 索引、关键章节和 git-aware 陈旧风险。
• 非极简项目缺少 docs/program-notebook.md 时，skill 会指示 Agent 基于证据直接创建；只读任务、用户禁止写入或极简项目除外。
• OpenCode 会在会话消息中注入 <program-notebook-status>，并记录本会话结构性改动。
• OpenCode 会记录 apply_patch、文件编辑和 bash 后的受关注文件改动。
• 对改动路径给出精确文档建议。

固定文档结构

• docs/program-notebook.md：中枢索引、项目摘要、当前状态、关键决策、进度、风险、已知缺陷、参考资料入口。
• docs/architecture/01-program-structure.md：完整程序结构框图、模块职责、关键依赖。
• docs/architecture/02-data-flow.md：运行时数据流、硬件反馈、网络路径、状态传播。
• docs/architecture/03-ci-pipeline.md：测试覆盖、CI 验证链路、质量门。
• docs/architecture/04-code-style.md：代码风格、复杂模块、维护风险、重构建议。

安装

Codex

已验证基线为 Codex CLI 0.151.0。安装时仍以功能检测为准：codex plugin --help 与 codex plugin marketplace --help 必须可用。本地 MCP server 使用随包发布的 Node.js bundle，不依赖 Bun。

codex --version
codex plugin --help
codex plugin marketplace --help
codex plugin marketplace add LycanW/program-notebook
codex plugin add program-notebook@program-notebook

安装后开启新会话，使 program-notebook skill 和 check_notebook MCP 工具生效。更新时先运行 codex plugin marketplace upgrade program-notebook，再重新运行 plugin 安装命令。

OpenCode

在 ~/.config/opencode/opencode.jsonc 或 ~/.config/opencode/opencode.json 中加入 npm 包名：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["program-notebook"]
}

插件会在启动时自动安装，并注册 /check-notebook 命令和 program-notebook skill。

重启 OpenCode 生效。OpenCode 不会热重载配置、插件、skill 或命令。

Kimi Code

1. 在 Kimi Code 中安装 plugin：

/plugins install https://github.com/LycanW/program-notebook

2. 运行 /reload 或开启新会话，使 plugin 生效。

Pi

从 npm 安装：

pi install npm:program-notebook

临时试用、不写入 Pi 配置：

pi -e npm:program-notebook

本包在 package.json 中声明 pi-package keyword 与 pi resources。发布到 npm 后可被 pi.dev/packages 收录和检索。

使用

Codex

Codex 会在任务匹配时隐式调用该 skill，但不会每轮重复注入；也可以显式调用：

使用 $program-notebook 检查当前项目的 notebook/docs 是否需要更新。

也可以让 agent 直接调用工具；调用时应把当前项目根目录传给 projectRoot：

请调用 check_notebook，把当前 workspace 根目录作为 projectRoot，并基于报告判断 notebook/docs 是否需要更新。

OpenCode

在 OpenCode 中可直接调用：

/check-notebook

或者让 agent 调用工具：

请调用 check_notebook，并基于报告判断 notebook/docs 是否需要更新。

Kimi Code

在 Kimi Code 中让 agent 调用工具：

请调用 check_notebook，并基于报告判断 notebook/docs 是否需要更新。

也可以指定项目根目录：

请调用 check_notebook，projectRoot 为 /path/to/project，并基于报告判断 notebook/docs 是否需要更新。

Pi

直接运行命令。命令会显式加载 skill：缺失 notebook 的非极简项目将由 Agent 创建文档，已有文档则按证据检查并同步。

/check-notebook

也可以让 agent 调用只读工具，或显式加载 skill：

请调用 check_notebook，并基于报告判断 notebook/docs 是否需要更新。
/skill:program-notebook 检查本次结构性改动是否需要同步文档

projectRoot 省略时使用 Pi 当前工作目录；相对路径也基于该目录解析。

Pi 版本采用缓存友好的按需策略：extension 不注册逐轮上下文注入事件；系统提示中只保留稳定的 skill 名称与描述，精简 SKILL.md 仅在任务匹配或显式调用时加载；详细结构规范与维护手册继续按需读取；状态报告仅在调用工具或命令时生成。

当任务涉及陌生代码库、跨模块改动、源码/配置/构建/测试/架构/数据流结构性变化时，agent 应加载 program-notebook skill。

面向 agent 的自动部署、维护和发布步骤见 AGENTS.md。

开发验证

bun install
bun run build:runtime
bun test
bun --print "await import('./.opencode/plugins/program-notebook.ts').then((m) => typeof m.default)"
bun test tests/pi-package.test.ts
pi -e ./extensions/program-notebook.ts --list-models
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/program-notebook
python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .

预期结果：测试全通过，OpenCode 插件导入输出 function，Pi extension 能加载，Codex skill 与 plugin 校验通过。

注意事项

• 不要把 lib/program-notebook-lib.ts 放进 .opencode/plugins/ 或 ~/.config/opencode/plugins/。
• OpenCode 会把 plugins/*.ts 的每个文件都当作插件入口自动加载。
• 只有 .opencode/plugins/program-notebook.ts 应作为插件入口。
• 插件报告是证据入口，不替代读取源码、配置、测试和文档。

License

MIT