Tenon
面向 coding agent 的本地优先工作流治理：显式状态、真实 Skill 来源证据、精确复核收据，以及始终展示实际 Workflow 的 Dashboard。
在线中文文档 · English ·
仓库内中文文档 · English guide ·
安全 · 参与贡献 · MIT License
Tenon 是一个完整打包的插件，不是“CLI 加一份需要手工安装的 Skills 清单”。发布包包含声明式 Workflow、OpenSpec 证据规则、入口 Skill tenon、hooks、CLI、本地 Dashboard、自动化控制和多宿主 adapters。
它解决 agent 工作中常见的错位：对话说了一套，任务状态、Todo、文档和实际工具执行却是另一套。Tenon 让这些界面共享同一份 Effective Workflow Plan，并拒绝无效转换，而不是从对话文本猜测进度。
它改变了什么
| 没有工作流治理 | 使用 Tenon |
|---|
| 旧任务可能仅因为“最近”而被恢复。 | 只有请求明确标识或要求恢复某个 Change 时才恢复它。 |
| 通用 Todo 可能与真实流程漂移。 | Todo 和 Dashboard 步骤来自所选 Workflow。 |
| Prompt 可以声称执行过 Skill 或读过文档。 | 系统校验当前访问的 Skill、文档摘要、读取、复核和转换收据。 |
| 所有任务都被迫经过同一套重流程。 | 讨论、轻量轨道、重型轨道和自定义工作流有不同且显式的结果。 |
| “支持某宿主”可能掩盖能力差异。 | Adapter 公布上下文注入、阻断和 Skill 留痕的 A/B/C 保真度。 |
选择正确的执行路径
| 路径 | 适用场景 | 形态 | 文档行为 |
|---|
| Discussion | 问答、解释、系统通知、斜杠命令 | 不创建 Change | 无受治理文档 |
轻量（default 的 lite 轨道） | 评估后预计改动未超出轻量阈值的修改 | open → build ⇄ verify → done，越界时 escalated | 不启用 OpenSpec 文档链 |
产品 / 前端 / 后端（default 的重型轨道） | 产品调研、功能、架构、鉴权、迁移、依赖等较大的工作 | open → explore → spec ⇄ build ⇄ verify → ship → archive | 离开每一步时记录实际产出与来源技能；门禁按路径检查 required-output |
| Custom Workflow | 项目自定义声明式流程 | 与编写的图完全一致 | 离开每一步时记录实际产出与来源技能；只检查它声明的 required-output |
轻重不按关键词猜。开发请求在建任务前先用 tenon assess --files 评估预计要改的文件：改动超过 8 个文件，或碰到契约、鉴权、依赖、迁移、删测试、受保护的测试配置中的任何一类，就推荐领域重型轨道；你确认后才创建任务。轻量任务在实现中越界时，改动风险探针会把它升级为重型任务。
了解路由与 Workflow →
Dashboard 一览
| 流程进度 | 工作流 |
|---|
| |
| Todo、阶段、门禁和执行来源保持同源。 | 工作流编辑器展示 Track、阶段、输入输出和技能编排。 |
| 工作流总览 |
|---|
|
| 默认与自定义工作流共享同一套可检查编排。 |
Dashboard 顶部保留工作台、工作流、项目、库、技能五个入口；主题和语言从设置菜单切换。宿主计划、AFK
和机器诊断继续由 CLI 与本地 API 提供，只读预览不会执行命令。
查看 Dashboard 完整图文指南 →
安装
前置要求
- Node.js 22 或更高版本
- Git
- 一个明确选择的宿主 CLI；Codex 用户可先运行
npm install -g @openai/codex，再用 codex --version 验证
- 只有使用 AFK 容器执行时才需要 Docker
新用户无需 clone 仓库。一次安装完整 Codex 插件：
/usr/bin/curl -fsSL https://raw.githubusercontent.com/jefferysha/tenon/v0.3.4/install.sh | /bin/bash -s -- --codex
Claude Code 用户只替换宿主参数：
/usr/bin/curl -fsSL https://raw.githubusercontent.com/jefferysha/tenon/v0.3.4/install.sh | /bin/bash -s -- --claude
先预览 Codex 的完整 Marketplace 与包内 setup 计划、且不调用宿主或写入用户目录：
/usr/bin/curl -fsSL https://raw.githubusercontent.com/jefferysha/tenon/v0.3.4/install.sh | /bin/bash -s -- --codex --dry-run
该命令始终从不可变稳定版本 v0.3.4 安装预构建发行资产，不 clone 仓库、不运行源码编译。
Bootstrap 注册 Tenon Marketplace、安装同一个完整插件、校验发行 payload，并执行
tenon setup --<host>。已经安装后的维护入口仍是 tenon setup --codex、tenon update --codex
与 tenon runtime status。
Tenon 版本号已重置为从 0.1.0 开始；已退役的 1.x Release 与标签已于 2026-10-07 删除（维护者保留归档）。如果机器上仍是 1.x 安装，
请为每个宿主各执行一次上面的版本化安装命令。1.x 上的 tenon update 只会报告降级且不做任何改动：
那段拒绝逻辑属于已经发布的 1.x，无法事后修补；因此也不把第二次命令或 Dashboard/校验脚本副作用
伪装成一键升级。从 v0.1.0 起，之后每次常规升级都只需运行一条 tenon update --codex（或 --claude），
且始终以稳定 release tag 为交付身份。
安装会启动并等待 Dashboard 就绪。curl/CI 安装不会自动打开浏览器，而会打印已验证 URL；需要时运行
tenon dashboard --open。交互式终端中的首次 tenon setup 可以自动打开，手动或后台更新不会。
Dashboard 不向未登录的调用方提供任何东西，所以直接访问 URL 只会看到登录提示：tenon dashboard --open
会替你打开已登录的浏览器（见登录）。
Codex 插件安装与账号认证是两个独立步骤。安装完成后，Tenon 只读运行
codex login status，不会自动登录或读取凭证内容。若尚未登录：
# ChatGPT 方案包含 Codex 时
codex login
# 远程或无浏览器环境
codex login --device-auth
# Platform API Key（先在 https://platform.openai.com/api-keys 创建）
printenv OPENAI_API_KEY | codex login --with-api-key
# 复核
codex login status
ChatGPT 方案登录通常无需另设 API Key；Platform API 使用单独的 API Key 与按量计费。不要把 Key
直接写进命令参数、日志或 Issue。
需要自动跟随后续发行版时显式启用每日检查：
tenon setup --codex --auto-update
Marketplace 是当前公开的一步安装入口；薄 npx 包已经纳入发布流水线，但只有拥有的 npm scope
真正发布后才会公布准确包名。旧身份用户由独立的 migration-only 仓库迁移，Tenon 主包不保留旧命令。
Codex setup 完成后，在 Codex 中运行 /hooks 并信任一次 tenon。然后新开宿主会话，使打包的 hooks 和 Skills 被加载。
tenon runtime status
tenon doctor
tenon dashboard --open
生产 Dashboard 是位于 http://127.0.0.1:18765/ 的单一本地 SPA 和 API。另一个 Vite 端口只用于前端开发。
安装、全部宿主与生命周期 →
第一个受治理任务
完成 setup 和 hook 信任后，在正常对话中直接提出真实工作：
为项目切换器添加键盘导航并编写测试。
路由器会为讨论跳过治理；开发请求先评估改动范围，再在轻量或领域重型 Track 上创建新的受治理 Change。它不会静默恢复无关旧 Change。
检查结果：
tenon list --json
tenon status <change-name> --json
tenon document status <change-name>
tenon dashboard --open
要恢复已知 Change，请在对话中明确说出它，或显式激活：
tenon session activate <change-name>
完整五分钟教程 →
Default Workflow 如何获得推进资格
open → explore → spec ⇄ build ⇄ verify → ship → archive
复核 复核 复核
↑ │
└ 需求变化 └ 验证失败 → build
每一步的 Skill 按它自己的 SKILL.md 写文件；只初始化状态不会自动产生有意义的内容。Tenon 在离开步骤时自动记录本步新增、修改、删除的文件和来源 Skill。下一步只拿直接上游产出的文档，必须读完（tenon document read）才能离开。
门禁只保留按路径的“必须产出”（required-output）：
- Open：
openspec/changes/{change}/proposal.md
- Explore：
docs/superpowers/specs/*.md
- Spec：
openspec/changes/{change}/specs/*/spec.md；前端、后端轨道另需 docs/superpowers/plans/*.md
- Verify（
verify-pass）：docs/superpowers/reports/{change}-verify.md
升级前创建的任务按冻结快照照旧。
Review 出口与确切 transition event 绑定：
tenon review request <change-name> --event <event>
# 用户确认之后：
tenon transition <change-name> <event>
确认只来自用户：回复放行语（“确认继续”“继续执行”等，由 hook 写入回执）、在 Dashboard 确认
（tenon dashboard --open），或由用户本人在自己的终端运行 tenon review acknowledge <change-name>；
agent 不得代为执行。
持续委托可以被记录，但不会豁免文档、Skills、guards、复核证据、安全边界、发布权限、费用或外部副作用。
Default Workflow → ·
文档、Skills 与证据 →
宿主 Adapter 保真度
Tenon 提供 12 个宿主目标，并显式标注执行保真度：
| 档位 | 宿主 | 含义 |
|---|
| A | Claude Code、Codex、Gemini CLI、Continue CLI、Cline、Amp | 上下文注入、阻断和留痕均有原生等价能力 |
| B | Cursor、GitHub Copilot coding agent、Pi、Aider | 一项或多项能力使用明确降级或更晚的执行点 |
| C | Devin、Zed | 静态指导加人工 CLI 收据；没有原生硬阻断 hook |
重要边界：
- Codex 需要一次本机 hook 信任。
- Continue 支持指 Continue CLI，而不是 IDE extension。
- Pi 的 veto 是 advisory；Aider 的 veto 在 commit 而不是写盘时发生。
- Amp 按 adapter 能力属于 A 档，但其 payload 细节尚未在有凭证的真实 Amp 会话中端到端验证。
完整宿主矩阵 →
产品界面
| 界面 | 职责 |
|---|
| CLI | Setup、runtime 生命周期、Change 状态、转换、复核、证据、Tracks、自动化与诊断 |
| Kernel | Workflow/Track 编译、状态、guards、ledgers、锁、CAS 和 loop policy |
| Hooks 与 adapters | 上下文注入、工具调用前阻断、Skill 留痕和宿主安装 |
| Dashboard | 在同一 loopback server 上提供项目、进度、AFK、配置、机器诊断与只读宿主计划 |
| AFK 与 loops | 可选沙箱工作、准入、预算、并发和 L1/L2/L3 升档 |
| Channel | 高级 event-sourced worker 通信；不修改 canonical Tenon state |
| Memory bridge | 只读本地会话发现和上下文提取 |
| Tap | 显式 opt-in 的本地流量诊断；捕获的 prompt、header 和 token 属敏感数据 |
文档
本地安全边界
Dashboard 绑定 loopback、校验本地 Host header、为 mutation 使用随机 handshake token、限制 JSON request body，并把文件操作限制在已注册项目根。受管 release 在激活前按内容寻址并重新校验。
这是本地单用户工作站模型，不是远程多租户控制面，也不声称防御同一 OS 用户下所有恶意进程。Tap interception 默认关闭。
CI 与 pre-tag release candidate 都运行 npm run check:dependencies。该单一门禁同时执行
High/Critical advisory audit 和 npm ls --all 完整解析树校验。正式发布必须先
对精确、仍为最新 main 的 40 位 SHA 手动运行 Release candidate (pre-tag)，并传入新 tag；
若恢复已中断发布，也可传入已精确指向同一 SHA 的现有 tag。只读验证 job
不会持有远端写凭据，并要求该 SHA 的 canonical push CI 已成功；全部构建、测试和打包也在这里完成，
输出由规范化后的 GitHub artifact digest 与逐资产 SHA-256 清单绑定的 payload。默认分支拥有的
workflow_run writer 会重新验证仓库、workflow、run、artifact 与 SHA；它不 checkout、不执行
仓库代码、不运行 npm lifecycle，只用最小写权限创建或恢复 tag，并校验或补齐 GitHub Release
资产。已存在 tag 仅在 peeled commit 与获批 SHA 精确一致时可幂等继续。发布自动化不执行
npm publish；可选 npx 包只作为 GitHub Release 资产。
安全模型 → ·
私密报告漏洞 →
从源码开发
仓库是 npm workspace，不对外声称已发布全局 npm CLI。
git clone https://github.com/jefferysha/tenon.git
cd tenon
npm ci
npm run build
npm test
npm run test:web
bash tools/test-hooks.sh
bash tools/test-adapters.sh
bash tools/verify-skills.sh
bash tools/test-bundle.sh
想让本机的技能、hooks 与 CLI 都用仓库工作区而不是已发布版本：tenon setup --claude --from-source .（Codex 用 --codex，先加 --dry-run 预览）；改完仓库后重跑同一条命令即可同步，切回正式版用 tenon update --claude --to-stable。详见贡献者开发。
Upstream Skills
Third-party Skills are not vendored. skills/sources.yaml lists每个上游 Skill 的
仓库、目录、许可证与 Tenon 使用的 id；tenon setup --<host> 与 tenon update --<host>
从每个仓库默认分支获取最新完整内容（含参考文件与脚本）写入宿主插件根的 skills/，
并把实际提交与内容哈希记进 skills/skills.lock.json（随发布包分发，不入 git）。
许可证只接受 MIT 与 Apache-2.0；缺许可证或许可证不符的 Skill 不安装。某个上游不可达时
该 Skill 保留已安装的旧版本，其余 Skill 不受影响，tenon doctor --skills 与 Dashboard
的技能页显示每个 Skill 的来源、提交、许可证、更新时间与状态。
开发 checkout 里运行一次即可获取同一批 Skill（获取到的目录不入 git）：
npm run skills:fetch
Bundled Skill provenance
templates/skill-sources.yaml is the one tracked provenance registry for every
Tenon-owned Skill. It is schema v3 (hash_algorithm: tree-sha256-v1): each
entry declares source_kind: bundled, a normalized source_ref, the
canonical sha256: content hash, and an immutable coordinate containing the
same identity and digest. Upstream Skills are proven by skills/skills.lock.json
instead, and the verifier accepts the union of both. The historical
skills-lock.json is removed and must not be reintroduced.
After changing a bundled Skill, refresh the registry explicitly and inspect
the diff:
npm run sync:skill-provenance
bash tools/verify-skills.sh --quiet --root "$PWD"
The hidden packaged command
tenon internal-skill-provenance verify|sync --root <path> [--json] is the
implementation behind these checks. verify is read-only; sync computes all
entries before atomically replacing the registry. Setup, doctor, release
candidates, and bundled lookup fail closed on an invalid registry, missing/extra
Skill, legacy lock, or content drift.
修改契约、生成资产、adapters、hooks 或分发文件前，请阅读 CONTRIBUTING.md。
项目状态与社区
Tenon 1.0 起，用户可见插件 manifest、workspace packages、Git tag 与可选 npx 发布包使用同一版本号。
文档描述当前 release 上已验证的行为；本地 Dashboard 不是托管服务，也不承诺远程 SLA。
