Tenetora
English

快速开始 ​

从空机器到受治理项目的最短可验证路径。安装 skill 包不会创建 .tenetora/；项目初始化是一个独立动作。

适用对象 ​

希望在自己的编码 Agent 中运行 Tenetora，并以证据收尾的开发者：安装真实生效、项目记录已初始化、校验通过——而不只是打印了版本号。

任务路径 ​

  1. 通过下方受门禁保护的入口安装或升级 skill 包。
  2. 核验安装：version、status、doctor。
  3. 用 tenetora-init 初始化项目记录。
  4. 验证基线：validate、run-all、audit、recap。
  5. 日常任务经 lifecycle skills 与动作 guards 进入受治理路径。
  6. 用 local-env 登记机器专属的本地环境路径，让 doctor 与 commit guard 能看护它们。
  7. 分清两条更新回路：skill 包升级与项目 .tenetora 更新。

安装或升级 skill 包 ​

生产安装入口已就绪（入口信息来自通过门禁的事实）

上方面板由 typed 事实层驱动。公开来源核验完成前，它展示证据状态而不是安装命令——这是有意设计的 fail-closed 行为，不是功能缺失。

门禁通过后，安装器的行为如下：

  • 交互终端第一步选择 English 或中文；自动化环境用 --lang 或 TENETORA_LANG 固定语言。
  • 首次安装可以创建 global、project 或 both scope。
  • 重复运行且不指定 scope 时执行 existing-only 升级：刷新机器注册表中的全部已有全局安装面、项目安装面与仅治理项目，不创建任何新安装。
  • 从已受治理项目启动时，还会有界发现同级 .tenetora 项目与能够证明归属的旧 .harness 目录。
  • 能力结果为 FULL、PENDING_TRUST、PARTIAL 或 BLOCKED；等待信任确认或重启属于安装成功状态，只有真实的部分失败或阻断才展示详细日志路径。
  • 全局安装只提供 Hook 运行时——治理由项目显式启用。没有 .tenetora/ 或旧 .harness/ 的工作区保持静默：不注入规则、不提醒、没有 commit 门禁、没有外部输入门禁。

CLI 安装完成后，日常升级直接使用它，不再获取远程脚本：

bash
tenetora upgrade --check
tenetora upgrade
tenetora upgrade --force

--check 只显示计划；裸 upgrade 执行已登记安装面的 existing-only 升级。upgrade 会先读取并认证远程 manifest。发布版本与当前 CLI 一致时报告"已是最新版本"，跳过 ZIP 下载与安装事务并成功退出；--force 只用于同一版本在修复后的重新收敛。从 0.2.x 过来的用户先用固定版本 bootstrap 进入 0.3 bridge 一次，之后统一使用 tenetora upgrade。

机器注册表的清理由你显式触发：

bash
tenetora installations --json list
tenetora installations --json prune --expired

list 把安装面标记为 stale，超过有界保留期的 stale 条目标记为 expired。prune --expired 绝不自动执行：它只移除机器注册表元数据——绝不删除项目目录、.tenetora、本地环境文件或第三方配置。

预览无 scope 升级会触及的范围：

bash
tenetora installations discover --auto --dry-run

基本要求：Python 3.9 或更高版本；原生 Windows 使用 PowerShell 安装器（install.ps1），不需要 Git Bash 或 WSL；原生 plugin 宿主安装后需要重启；Codex 可能需要在 /hooks 中确认信任。离线 ZIP、预检、重置和排障见随源码仓库发布的完整安装指南（每页导航均有仓库链接）。

核验安装 ​

bash
tenetora version
tenetora status --tools all --scope both --path . --verbose
tenetora doctor --tools all --scope both --path .

成功不只是 tenetora version 能输出版本。status 必须指出每个工具的实际生效来源，doctor 必须解释信任、重启、runtime 未激活或平台能力限制等后续动作。Attention 是需要处理的证据，不能只检查版本来隐藏它。

若 tenetora 不在 PATH，使用当前宿主 skill 的 ensure_cli.py --install --json 返回的绝对 command。不要持久化工具私有的 PYTHONPATH 调用或 alias。

初始化项目 ​

在 AI 工具中：

text
use tenetora-init 初始化 .tenetora

已有仓库的 CLI 等价命令：

bash
tenetora init --tools auto --write --gitignore yes --migrate plan --mode extract --defaults missing

空仓库使用 --mode scaffold；迁移和备份决策确认前保持 --entrypoints plan。证据提取的事实必须带 source path；推断保持标签；未知架构和命令明确记录为未知，不能凭空生成。

验证基线 ​

bash
tenetora validate --path .
tenetora run-all --path .
tenetora audit --strict --path .
tenetora recap --write --path .

validate 证明项目记录在结构上可消费；run-all 证明已配置 guardrail 通过；audit 报告质量和剩余治理 finding。它们都不替代仓库自身的 build 和 test 命令。

开始大范围工作前读取 .tenetora/README.md、.tenetora/changes/INDEX.md 和 .tenetora/state/current-evidence.json——先看当前指导，而不是翻历史 archive。

升级 skill 包与更新项目是两件事 ​

这是两条互相独立的回路，谁也不能替代谁：

  • skill 包升级刷新机器上的 skills、plugin 与 runtime 安装面，使用上方安装入口。
  • 项目更新刷新单个仓库 .tenetora/ 内的治理内容：
text
use tenetora-update 更新 .tenetora

skill 包升级后检查已知项目修复：

bash
tenetora repair --check --path .

安装 skills 不会创建 .tenetora/；更新 .tenetora 也不会创建新的 skill 安装面。

保护本地环境文件 ​

项目常依赖机器专属文件——.env、本地配置、证书——它们绝不能进入 Git 或共享 evidence。登记项目相对路径，不保存任何内容：

bash
tenetora local-env --path . --allow config/local/app.conf
tenetora local-env --path . --list --json
  • tenetora status 与 tenetora doctor 会报告已登记路径消失以及登记表损坏——只读检查，绝不读取文件内容。
  • commit guard 把登记路径视为敏感路径，阻止它们进入暂存区。
  • 宿主能同时提供结构化工具名与路径时，PreToolUse 拒绝针对登记路径的高置信度破坏操作；无法两者都解析的宿主绝不做猜测性阻断。

绝不要为了通过检查而提交本地环境文件——登记的目的就是让它们留在本机。需要恢复时先检查项目 checkpoint，而不是删除文件去迎合 guard。

日常高风险边界 ​

bash
tenetora rules --context <context> --path .
tenetora guard --action commit --commit-message-file /path/to/commit-message.txt --require-message --path .
tenetora guard --action external-input --file /path/to/untrusted-input.txt --source "issue-report" --path .
tenetora guard --action claim --claim-kind completion \
  --session-id <session-id> --owner-id <owner-id> \
  --conversation-id <conversation-id> --tool <tool> \
  --verification-command "<完整验收命令>" --verification-status passed --path .
  • 局部检查使用 --claim-kind partial-verification，它不能满足完成门禁。
  • completion claim 必须绑定当前 owner 对应的 alignment session 与有效 goal fingerprint，用 --expected-verification-command 重复匹配同一条命令，且当前 Git 工作树不能发生变化。
  • 无法完成时使用 --claim-kind blocked 或 --claim-kind failed，不得伪造 passed proof。
  • 跨对话继续任务时不能复用旧对话的 claim proof：先检查 owner 绑定的 alignment session，再携带当前 session 和 conversation 身份重新 claim。

alignment proof、claim proof、commit 权限和 push 权限互相独立。任何 skill 或 hook 都不会自动授予 commit、push、部署或发布权限。

限制 ​

  • 公开来源核验完成前，不提供推荐安装命令；第三方帖子中的命令不具备权威性。
  • validate、run-all、audit 检查治理健康度，不替代项目自身的 build 与 test 命令。
  • guards 检查动作边界并生成证据，本身从不创建授权。
  • PreToolUse 保护需要宿主的结构化数据；skills-only 宿主上，可用层是 commit guard 加 doctor/status。

下一步 ​

  • 阅读概念了解这些命令背后的治理模型。
  • 查看集成完成你的平台要求的后续动作。
  • 查看安全了解外部输入边界。