TanmiWorkBase

TanmiWorkBase 是一个工作空间编排基础仓库。

它的职责只有三类：

1. 定义工作空间的结构化规范
2. 提供初始化与校验所需的模板
3. 提供最小命令行工具，用于创建、检查、解释工作空间

它当前不承载以下能力：

1. 不承载业务仓库源码
2. 不承载运行时服务
3. 不承载任务调度、状态机、页面界面、插件系统
4. 不承载跨机器同步能力

四层结构

1. 根级：<workspace-root>
2. 项目级：<workspace-root>/<project>
3. 需求级：<workspace-root>/<project>/<index>
4. 仓库级：<workspace-root>/<project>/<index>/<store>

当前定位

第一版先聚焦三件事：

1. 规范文件与模板文件的组织方式
2. 工作空间配置文件的字段草案
3. 最小 CLI 骨架与后续实现边界

仓库结构

TanmiWorkBase/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── pyproject.toml
├── docs/
├── examples/
├── schemas/
├── src/
├── templates/
└── tests/

首批命令草案

1. setup
2. init-project
3. init-index
4. validate
5. sync
6. cmd
7. collapse
8. expand
9. inspect
10. generate-agents
11. doctor

当前状态

本仓库目前处于实施草稿阶段。

请优先阅读以下文件：

1. docs/architecture.md
2. docs/implementation-draft.md
3. schemas/
4. templates/
5. examples/config-templates/

NPM 安装入口

本仓库准备以公开 NPM 包 tanmiworkbase 发布。NPM 包提供命令入口，实际运行现有 Python CLI。

安装方式：

npm install -g tanmiworkbase

安装后可使用两个等价命令：

tanmiworkbase --help
wb --help

运行要求：

1. 本机需要安装 Python 3.11 或更高版本
2. 本机需要安装 Node.js 18 或更高版本
3. NPM 包会把命令参数透传给 tanmi_work_base.cli
4. 执行发布前检查需要本机安装 uv

发布前检查：

npm run test
npm run pack:check
npm run publish:check

可直接编辑的 JSON 模板

如果你希望直接对着完整 JSON 改，不看 .j2 模板，可以优先修改这里：

1. examples/config-templates/workspace.config.template.json
2. examples/config-templates/project.config.template.json
3. examples/config-templates/index.config.template.json

这三份文件是“完整可编辑样板”，面向人阅读和修改。

templates/ 下的 .j2 文件仍然保留给工具生成使用。

当前字段口径已经收敛为：

1. 三类配置都必须显式写 schemaVersion: "0.1"
2. 根级与项目级统一使用 description
3. 项目级 defaultStores 保存项目默认仓库信息
4. storeType 采用受控自由字符串，推荐值写在模板与文档中
5. commands 统一使用 prepare、run、build、release 四组数组
6. 需求级 stores 默认只写覆盖项；如果是项目级未声明的临时仓库，则写完整定义

配置事实源分工：

1. schemas/ 是配置契约的唯一规则源
2. examples/config-templates/ 是最新完整模板源
3. README.md 与 docs/ 负责解释规则与使用方式
4. tests/ 负责检查 schema、模板、样例和 CLI 输出是否一致

说明字段写法约定：

1. 根级与项目级 description 只写定位、长期协作关系和默认链路摘要
2. 需求级 purpose 只写本次需求的目标、联调对象和预期结果
3. 具体命令写入 commands
4. 仓库、分支与 clone 策略写入 defaultStores 或 stores
5. 特殊限制写入 relations 或 extraRules

commands 当前边界约定：

1. commands 是结构化动作清单，不是自动执行授权
2. 默认不会自动执行任何 commands
3. 人工可以通过 wb cmd run 显式执行配置中登记的命令
4. prepare、run、build、release 统一保留为人工决策动作
5. 任何 Git 写操作、发布动作、外部系统写操作都不属于默认可代劳范围

当前 CLI 的第一版实现进度：

1. setup：已实现第一版根级初始化
2. init-project：已实现第一版项目级骨架初始化
3. init-index：已实现第一版需求级骨架初始化
4. validate：已实现
5. inspect：已实现
6. sync：已实现第一版静态同步
7. cmd：已实现人工命令查看与执行
8. collapse：已实现需求级声明仓库收起
9. expand：已实现需求级声明仓库展开
10. generate-agents：已实现第一版托管区块生成
11. doctor：已实现第一版诊断汇总

setup 当前只做：

1. 生成 .workspace-meta/workspace.config.json
2. 生成根级 README.md，用于长期维护说明与配置入口
3. 通过 generate-agents 生成根级 AI 入口文件；AGENTS.md 是主维护入口，CLAUDE.md 通过托管区块引用同级 AGENTS.md
4. 已有冲突文件时直接失败，不覆盖现有内容
5. 可选参数：--description

setup 第一版安全初始化策略：

1. 只初始化当前目录，不自动创建父目录
2. 根级目标文件只要发生冲突就直接失败
3. 不覆盖现有 README.md、AGENTS.md、CLAUDE.md、workspace.config.json
4. 不合并已有内容，也不自动清理现场

init-project 当前只做：

1. 在 workspace 根级下创建 <projectId>/project.config.json
2. 在项目级目录创建项目级 AI 入口文件
3. 输出完整的项目级后续引导
4. 默认使用 projectId 作为 displayName
5. 需求目录仍由后续 init-index 创建
6. 可选参数：--display-name、--description

补充说明：

1. init-project 第一版生成的是待补充模板
2. 因为 defaultStores 初始为空，刚生成的项目配置在补齐前可能无法通过完整语义校验
3. 项目级 AI 入口文件的托管区块会在后续执行 generate-agents 时按当前状态自动收缩
4. 补 defaultStores 时，需要逐仓确认 clonePolicy
5. 拉取仓库时执行 sync 获取当次提示；详细策略说明由 wb guide clone-policy 承载

init-index 当前只做：

1. 在项目级目录下创建 <indexId>/index.config.json
2. 自动继承上层 projectId
3. 立即生成需求级 AI 入口文件
4. 输出完整的需求级后续引导
5. 第一版不再生成独立的 index.notes.md，也不创建仓库目录
6. 可选参数：--purpose

补充说明：

1. init-index 第一版生成的是待补充模板
2. 因为 stores 初始为空，刚生成的需求配置在补齐前可能无法通过完整语义校验
3. 需求级待办与补充说明已经并入 AGENTS.md，后续执行 generate-agents 时会按当前状态自动收缩
4. 如果 stores 里新增完整仓库定义，也需要逐仓确认 clonePolicy

sync 当前只做：

1. 归一到需求级目录
2. 基于当前配置与现场输出结构化同步计划
3. 在 --apply 时创建缺失的空目录
4. 不自动处理复杂 Git 状态、分支收敛或命令执行

sync --json 当前固定输出：

1. 顶层字段：targetPath、level、normalizedIndexRoot、applyRequested、canApply、valid、validation、actions、errors、warnings、appliedPaths
2. actions[*] 字段：action、storeId、dirName、source、path、note、expectedBranch、remote、storeType、clonePolicy、commands、commandSummary、commandPlan、nextSteps
3. commands 与 commandPlan 用于展示动作细节，供 AI 或人工决定是否执行
4. nextSteps 用于表达当前仓库的建议后续动作，不表示工具会直接代劳

cmd 人工执行约定：

1. wb cmd list 可在项目级、需求级、仓库级查看命令
2. 项目级只查看默认仓库命令，不直接执行
3. 需求级执行格式：wb cmd run <storeId> <stage> <name>
4. 仓库级执行格式：wb cmd run <stage> <name>，也可显式写完整参数
5. stage 只允许 prepare、run、build、release
6. 默认执行前需要人工确认；--yes 可以跳过确认
7. release 阶段默认需要输入 release yes 才继续

collapse / expand 仓库收起与展开约定：

1. 只处理需求级 index.config.json 中声明的代码仓库
2. 非代码仓库内容保留在原位置，例如调试输出、日志、临时文档和资源目录
3. 默认只预览；加 --apply 后才会写入状态、生成补丁并移动仓库目录
4. 状态文件写入 <index>/.workspace-meta/repo-collapse/
5. 收起前会筛查未提交文件；单个文件不超过 2KB 的代码修改保存到 changes.patch
6. 单个文件超过 2KB 时不进入 patch；需要保留的文件按确认文件独立保存到 large-files/
7. 超过 2KB 且明显属于依赖、构建产物、缓存、内嵌 Git 或 ignored 资源的内容默认不保存，预览与状态中只记录统计结果
8. 超过 2KB 且不能自动判断用途的文件会阻止执行，需要先填写 --screening-decisions 确认保存或忽略，并为保存项标注功能
9. 存在本地提交且不能确认远端可恢复时，保存 local.bundle
10. 收起后自动刷新需求级 AI 入口文件，在 AGENTS.md 中加入 generated.repo-collapse 恢复提示
11. 展开时按 remote 与 clonePolicy 重新克隆，再导入 bundle、应用 patch、复制独立大文件
12. 展开目标目录已经存在时直接停止，避免覆盖本地内容

collapse 预览判断约定：

1. valid=true 只表示工具具备执行条件，不等于业务上建议立即执行
2. 文本输出和 JSON 输出都只面向执行判断，不输出完整文件级明细
3. decision.recommendedAction 表示下一步建议，例如先查看提示再执行
4. summary 汇总仓库数量、阻断数量、提示数量、干净仓库数量和存在修改的仓库数量
5. size.estimatedFreedBytes 表示收起仓库目录后预计释放的空间
6. restorePlan.head 表示展开时会恢复到收起前的提交，即使远端分支之后继续前进
7. changeScreening.thresholdBytes=2048 表示单文件 patch 上限
8. changeScreening.summary 汇总进入 patch、独立保存、默认忽略和待确认的文件数量与大小
9. changeScreening.decisionTemplate 是大文件确认模板；保存项需要填写 functionLabel
10. excludedSummary 汇总 ignored 内容数量、大小与分类，默认不保存依赖目录、构建产物、缓存和 ignored 资源
11. excludedSummary.manualReviewRequired=true 表示 ignored 内容中存在资源二进制等需要确认的内容
12. unmanagedEntries 表示需求级目录中不会被处理的非仓库内容或未声明仓库
13. ignored 内容不进入 changes.patch；恢复后依赖项目自己的依赖安装、资源下载或构建命令重新生成
14. git.dirtyEntries、git.excludedEntries、changeScreening.entries 不属于对外输出契约；工具内部只在生成补丁和确认模板时使用这些临时明细

collapse / expand 常用命令：

1. 预览全部声明仓库：wb collapse <index>
2. 预览单个仓库：wb collapse <index> --store <storeId>
3. 输出大文件确认模板：wb collapse <index> --store <storeId> --json
4. 实际收起单个仓库：wb collapse <index> --store <storeId> --apply
5. 带大文件确认执行：wb collapse <index> --store <storeId> --apply --screening-decisions <json-file>
6. 从仓库目录预览：wb collapse <store>
7. 预览恢复：wb expand <index> --store <storeId>
8. 实际恢复：wb expand <index> --store <storeId> --apply

版本不匹配时的迁移提示约定：

1. 报错必须明确指出当前支持的 schemaVersion
2. 报错必须直接给出对应层级的完整模板路径
3. 报错必须明确提示“不要只改 schemaVersion”
4. 报错必须明确提示“先按模板重建当前文件骨架，再迁移旧配置中的有效业务内容”
5. 迁移时优先保留说明文字、仓库定义、分支覆盖、特殊规则等业务信息，不沿用旧版本结构字段

generate-agents 当前只做：

1. workspace 入口生成工作空间根级 AI 入口文件
2. project 入口生成项目级 AI 入口文件
3. index/store 入口统一生成需求级 AI 入口文件
4. 如果发现旧的 project.notes.md 或 index.notes.md，会先迁移可识别的人工内容；确认没有未识别托管区块后再删除旧文件
5. AGENTS.md 只更新 generated.* 托管区块，自动保留或补齐 manual.* 区块
6. 需求级 AGENTS.md 自动保留或补齐 working.* 区块，用于记录当前需求的重点信息与最小进行态
7. CLAUDE.md 只更新 generated.claude-instruct 托管区块，通过 @AGENTS.md 引用同级主入口

generate-agents 第一版固定托管区块：

1. generated.workspace-summary
2. generated.project-summary
3. generated.project-guidance
4. generated.index-summary
5. generated.index-guidance
6. generated.repo-collapse
7. generated.claude-instruct
8. manual.notes
9. working.key-notes
10. working.progress

doctor 当前只做：

1. 汇总 validate 的错误与警告
2. 汇总 inspect 的现场摘要
3. 在需求级或仓库级附带 sync 的 dry-run 预览
4. 给出当前目录的建议下一步

根级配置位置

根级工作空间配置统一放在：

<workspace-root>/.workspace-meta/workspace.config.json

第一版根级 .workspace-meta/ 的稳定文件固定为：

1. workspace.config.json

AI 入口托管区块

AGENTS.md 的自动生成部分统一采用托管区块语法：

<--- TANMIWORKBASE:generated.workspace-summary --->
...
<--- /TANMIWORKBASE:generated.workspace-summary --->

需求级使用 generated.index-summary，人工补充内容应写在 manual.* 区块中，工具不会覆盖。

需求级还会使用两个 working.* 区块：

1. working.key-notes：记录当前需求中已经确认、反复查找、容易理解错或会影响后续判断的重点信息
2. working.progress：记录当前仍需继续处理的事项，使用树形 Markdown 任务列表维护最小进行态

working.* 区块由 AI 与人工维护正文，工具只负责创建、补齐和保留。结构化事实仍以 index.config.json 为准；阶段完成并验证后，应删除 working.progress 中对应待办分支。

CLAUDE.md 使用 generated.claude-instruct 区块引用同级 AGENTS.md：

<--- TANMIWORKBASE:generated.claude-instruct --->
@AGENTS.md
<--- /TANMIWORKBASE:generated.claude-instruct --->

CLAUDE.md 中托管区块以外的人工内容会保留。

版本迁移命令约定：

1. 第一版不提供单独的版本迁移命令
2. 版本不匹配时统一走校验报错与模板重建引导