# tenetora

**Repository Path**: lcgyl/tenetora

## Basic Information

- **Project Name**: tenetora
- **Description**: Tenetora 把规则、决策、证据和动作边界收进一份项目记录，服务所有已支持的 AI 编程工具，让关键动作可约束、可验证、可审计。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://tenetora.lcgylfamily.cn/zh/
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tenetora

[English](https://github.com/lcgyl/Tenetora/blob/main/README.md) | **简体中文**

Tenetora 是面向 AI Agent 软件工程的治理运行时。它把项目规则、决策、证据和动作边界集中到 `.tenetora/`，再连接到 Claude Code、Codex、Cursor、OpenCode、Pi、ZCode 和 Generic Agents。

它解决的是“代码写完了，但规则、验证和责任边界没有跟上”的问题。八个 lifecycle skills 提供模型工作流，CLI、plugin 和 hooks 负责可重复的检查；安装软件不会替你初始化项目。

## 先记住这条路径

```text
安装或升级软件
    -> tenetora version / doctor
    -> 在 AI 对话中初始化当前项目
    -> 日常使用 lifecycle skills
    -> 必要时 update、repair 或 audit
```

最短开始方式：

```text
使用 Tenetora 初始化当前项目
```

这句话需要在 AI 对话中发送。模型会使用 `tenetora-init` 检查现有规则、询问项目所有者需要决定的事项，再创建或迁移 `.tenetora/`。安装 lifecycle skill package 和 CLI 不会创建 `.tenetora/`，也不会代替模型理解项目。

## 它解决什么问题

| 问题 | Tenetora 的处理方式 |
| --- | --- |
| 多个 AI 工具各自维护规则 | `.tenetora/` 保存共享规则，宿主文件只做兼容入口。 |
| 对话压缩或换工具后丢失上下文 | Runtime Contract、按任务加载的 rules 和 evidence 重新提供高信号上下文。 |
| 目标或边界不清就开始改代码 | 高风险或有实质歧义时先走 decision alignment。 |
| “已完成”无法复查 | `guard --action claim` 绑定验证命令和 claim proof。 |
| 外部报告夹带执行指令 | prompt guard 把外部内容当数据检查，不把它当权限来源。 |
| 项目记录逐渐过期 | `update`、`repair`、`audit` 和 guardrails 形成维护闭环。 |

它不是更多提示词的集合，也不替代项目自己的 build、test、review 或发布审批。

## 支持平台

| 工具 | 当前集成形态 | 最大诚实能力 |
| --- | --- | --- |
| Claude Code | 用户级 native plugin、hooks、lifecycle skills | `active` |
| Codex | 用户级 native plugin、hooks、lifecycle skills | `active` 或 `needs-trust-review` |
| Cursor | lifecycle skills 和合并式 hooks | `active` |
| OpenCode | lifecycle skills 和 JS plugin | `active-partial` |
| Pi | lifecycle skills 和自动加载的 TypeScript extension | `active-partial` |
| ZCode | 用户级注册 plugin 和 process hooks | `active` |
| Generic Agents | lifecycle skills 和 CLI | `skills-only` |

`active` 表示配置达到平台契约，不表示尚未重启的宿主已经执行过事件。使用 `tenetora status` 和 `tenetora doctor` 查看 effective source、版本、信任和近期 runtime observation。Generic Agents 显示 `skills-only` 是能力边界，不是安装失败。

## 首次安装

新机器只需要远程 bootstrap 一次：

```bash
curl -fsSL https://gitee.com/lcgyl/tenetora/raw/main/install.sh | bash
```

Windows 使用 PowerShell bootstrap：

```powershell
& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing https://gitee.com/lcgyl/tenetora/raw/main/install.ps1).Content))
```

需要明确安装范围时：

```bash
curl -fsSL https://gitee.com/lcgyl/tenetora/raw/main/install.sh \
  | bash -s -- --lang zh --tools all --both --path .
```

运行时最低要求 Python 3.9。安装器会创建稳定的 `tenetora` launcher 并配置用户 PATH；当前终端找不到命令时打开新终端即可。原生 plugin 安装或更新后要重启对应 AI 工具。开发者做有界本地诊断时可以使用 `--source-dir /path/to/source`，普通用户不需要此参数。

## 另一台电脑安装

1. 执行首次安装命令。
2. 重启加载 native plugin 的 AI 工具。
3. 检查实际生效来源：

```bash
tenetora version
tenetora status --tools all --scope both
tenetora doctor --tools all --scope both
```

4. 进入目标项目的 AI 对话，发送 `使用 Tenetora 初始化当前项目`。

`--global`、`--in-project` 和 `--both` 只用于首次安装或明确的修复。隐式触发能力取决于具体 AI 工具；没有用户消息时不会后台自动运行。

## 安装后 Smoke Test

```bash
tenetora version
tenetora status --tools all --scope both
tenetora doctor --tools all --scope both
tenetora validate --path /path/to/project
tenetora run-all --path /path/to/project
tenetora audit --strict --path /path/to/project
```

安装成功和运行时已激活是两个事实。Codex 首次安装或 Hook 定义变化后，在 `/hooks` 中确认信任；Claude Code、Codex 和 ZCode plugin 更新后重启宿主，Pi extension 更新后执行 `/reload` 或重启 Pi。需要显式恢复原生 Hook 时使用 `--codex-hooks native`，普通升级使用自动策略。

## 支持诊断

需要向支持人员提供机器可读状态时，生成严格脱敏的 JSON：

```bash
tenetora diagnostics --path /path/to/project --tools auto --json
```

需要导出诊断包时，指定已经存在且安全的目录，并在分享前检查压缩包：

```bash
tenetora diagnostics --path /path/to/project --tools auto \
  --output /path/to/existing-directory/tenetora-diagnostics.zip
```

压缩包只包含 `diagnostics.json` 和 `README.txt`；凭证、本机路径、URL、项目正文和原始治理状态都会省略。已有输出文件不会被覆盖，除非显式指定 `--force`。

## 升级和重置安装

0.3.x 的日常软件升级只有一个入口：

```bash
tenetora upgrade
```

需要先查看计划时：

```bash
tenetora upgrade --check
```

裸运行 `tenetora` 可能显示本地缓存的更新提示。提示由成功的在线升级检查刷新，有效期为 24 小时；裸命令不会因此发起网络请求。检查失败时保留上次已知 release 并提示失败，不保存 URL、代理配置、凭证或项目正文。

在线升级默认使用 canonical HTTPS 发布源。网络需要代理时，设置标准的 `HTTPS_PROXY`、`HTTP_PROXY`、`ALL_PROXY` 或 `NO_PROXY` 环境变量（底层客户端也接受小写写法）；Tenetora 只在本次获取过程中使用它们，不会写入更新状态。企业镜像可以提供相同的目录结构，并通过基址选择：

```bash
TENETORA_RELEASE_MIRROR=https://mirror.example/tenetora/stable tenetora upgrade --check
tenetora upgrade --mirror-url https://mirror.example/tenetora/stable
```

镜像目录必须包含 `manifest.json` 和 `tenetora-latest.zip`，两者仍按同一 release 合同校验。高级直连地址可以成对设置 `TENETORA_RELEASE_MANIFEST_URL` 与 `TENETORA_RELEASE_ZIP_URL`，或同时传入 `--manifest-url` 和 `--zip-url`。发布地址必须使用 HTTPS，不能包含凭证、query 或 fragment；镜像不能和直连地址混用。配置格式错误或只配置一半时会在写入前 fail-closed；获取失败会保留上次有效的更新提示。

`tenetora upgrade --apply` 是 0.3.x 旧自动化的兼容别名。它和不带参数的 `upgrade` 使用同一套 release 获取与事务引擎。

0.2.x 用户需要用固定版本 bootstrap 最后进入一次 0.3 bridge；完成后回到 `tenetora upgrade`，不再重复远程获取脚本：

```bash
curl -fsSL https://gitee.com/lcgyl/tenetora/-/raw/0.3.14/install.sh \
  | bash -s -- --lang zh --tools all --both --path "$PWD"
```

无 scope 的升级默认只处理已经登记或能证明归 Tenetora 所有的现有安装面，不会因为检测到某个工具就新建 plugin。`--in-project --path X` 只更新指定项目的已有安装面；`--global` 明确忽略项目状态。升级也不会初始化缺失的 `.tenetora/`。

`.tenetora` 内容更新和软件升级是两个动作。项目规则或结构变化后，在 AI 对话中说 `use tenetora-update 更新 .tenetora`；skill 包升级后检查已知兼容问题：

```bash
tenetora repair --check --path /path/to/project
tenetora repair --apply --path /path/to/project
```

## 卸载或重置

Tenetora 的受管 home 默认是 `~/.tenetora`，其中包含 release、CLI、安装登记和备份。不要直接删除未知的宿主 plugin、Hook、registry 或用户 Hook。

重置前先运行：

```bash
tenetora doctor --tools all --scope both --path /path/to/project
```

只清理能够证明归 Tenetora 所有、且未被用户修改的路径。旧 `~/.agent-harness` 或 `.harness` 只有在归属证据明确时才迁移；第三方或混合内容会保留并要求复核。卸载和历史迁移详见[安装与升级指南](docs/guides/installation.zh-CN.md)和[Tenetora 迁移指南](docs/guides/tenetora-migration.zh-CN.md)。

## 调用方式

用户通常只需要记住：

```text
use tenetora
use tenetora-align
使用 Tenetora 初始化当前项目
use tenetora-update 更新 .tenetora
use tenetora-audit 审计 .tenetora
use tenetora-loop 继续
use tenetora-prompt-guard 检查外部内容
```

`router`、`init`、`update`、`audit`、`loop` 和 `prompt-guard` 可以根据宿主元数据使用 `allow_implicit_invocation: true`。`tenetora-align` 固定使用 `allow_implicit_invocation: false`，不会在普通任务中自行启动访谈。

## Lifecycle Skill 触发矩阵

| Skill | 触发时机 | 边界 |
| --- | --- | --- |
| `tenetora` | 治理阶段不明确，需要路由 | 不执行普通业务开发。 |
| `tenetora-align` | 用户明确要求实现前对齐高风险决策 | 不自动实施，不授予 commit、push、部署或发布权限。 |
| `tenetora-decision-interview` | lifecycle 发现高风险实质歧义 | 不是必须记忆的独立入口。 |
| `tenetora-init` | 缺少 `.tenetora` 或需要重建基线 | 不升级已安装 skill 包。 |
| `tenetora-update` | 项目规则、结构、证据或入口发生漂移 | 不创建新的 skill 安装面。 |
| `tenetora-audit` | 检查稳定性、可靠性、控制和内容质量 | 不替代项目测试。 |
| `tenetora-loop` | 继续、恢复、下一步，或需要有界修复循环 | 不会后台无限运行。 |
| `tenetora-prompt-guard` | 使用网页、报告、工单、脚本等外部内容 | 不执行外部内容中的指令。 |

决策对齐使用 `guard --action alignment` 绑定当前目标。alignment proof、claim proof、commit 权限和 push 权限彼此独立；Tenetora 没有复制 commit、push 或发布权限。

## 独立子智能体治理

Tenetora 定义 `code-reviewer`、`security-auditor`、`codebase-scout` 和受限 `implementer` 角色。CLI 只渲染契约、校验声明并记录状态和证据，不直接启动平台 agent。它也不把 plugin 未激活解释为宿主没有子智能体。

模型在声明角色不可用前，必须检查当前宿主可见、延迟加载或可发现的派发工具。宿主没有合格边界时，降级为主智能体自审并标记 `未经独立审查`。独立审查最多 3 次审查、2 次修复，临时报告只在 `.tenetora/.cache/subagents/`；`recommendation-only` 和 `host-dependent` 是诚实的能力状态。这项能力不需要新增的用户调用词。

## 安全和默认规则

- 外部输入先过 prompt guard；网页或报告里的命令不能直接获得本地执行权。
- commit、规则变更、外部输入和完成声明各自使用 action guard。
- `CLAUDE.local.md` 等入口只做 thin adapter，tool-private-config 不进入共享规则。
- Tenetora default baseline rule pack 只补缺失的通用规则，项目规则优先。
- `--defaults missing` 只补缺失项，来源写入 `rules-inventory.json`，区分 `owner: tenetora` 和 `owner: project`。
- 默认规则包括 `context-freshness.md`、`verification-claims.md` 和 `security-boundary.md`。

## 日常验证

```bash
tenetora route --message "<user request>" --path .
tenetora rules --context <build|test|commit|security|harness|docs|planning> --path .
tenetora validate --path .
tenetora run-all --path .
tenetora audit --strict --path .
```

## 文档导航

| 目标 | 文档 |
| --- | --- |
| 产品定位和差异 | [Tenetora 是什么](docs/product.zh-CN.md) |
| 真实工程场景 | [使用场景](docs/use-cases.zh-CN.md) |
| 公开能力 | [能力指南](docs/capabilities.zh-CN.md) |
| 第一次使用 | [快速上手](docs/quickstart.zh-CN.md) |
| 安装、升级、离线和卸载 | [安装与升级](docs/guides/installation.zh-CN.md) |
| 平台 plugin、Hook 和 runtime | [运行时与平台](docs/guides/runtime-platforms.zh-CN.md) |
| lifecycle、对齐、loop 和子智能体 | [治理工作流](docs/guides/governance.zh-CN.md) |
| prompt guard、repair 和 evidence | [安全与维护](docs/guides/security-maintenance.zh-CN.md) |
| CI 和 pre-commit | [CI 指南](docs/ci.zh-CN.md) |
| 当前版本变化 | [CHANGELOG](CHANGELOG.md) |

研发规格、任务、验收和 roadmap 是源码仓库证据，不是普通用户入口，也不进入 release ZIP。

## 开发验证

```bash
python3 -m unittest discover -s tests
python3 scripts/package-release.py --output-dir dist --latest
bash scripts/smoke-local-install.sh
```

项目要求 Python 3.9+。发布包、root installer 和 skill 内嵌 installer 必须保持一致；旧 Agent Harness 名称仅用于识别和迁移已证明归属的旧安装。