ZENVAULT PM / 禅曜

让禅道负责事实，让 Obsidian 留住判断

English · 简体中文

一套连接 ZenTao 与 Obsidian Project Manager 的 Codex Skills。 从执行中拉取需求与任务，在熟悉的笔记工作台里推进，再把确认过的变化增量送回禅道。

安装整套 Skills · 开始使用 · 安全边界 · 升级

一条不对称的双向航线

                                  个人计划 · 会议 · 判断 · 复盘
                                               │
                                               ▼
┌──────────────────┐   PULL   ┌────────────────────────────────┐
│ ZenTao Execution │ ───────▶ │ Obsidian · Project Manager     │
│ 需求 / 任务 / 状态 │          │ 可查看、整理并编辑允许回写的字段 │
└──────────────────┘ ◀─────── └────────────────────────────────┘
        事实源          PUSH                 工作台
                  仅差异 · 先预览 · 再确认

这不是把两个系统做成镜像。ZenTao 始终保存结构化项目事实；Obsidian 承载个人工作，并通过隐藏基线识别真正发生过的修改。正文、备注、会议记录和私有判断不会因为同步进入禅道。

五个 Skill，一套完整闭环

| Skill | 你可以这样说 | 它负责什么 | | --- | --- | --- | | zenvault-setup | “帮我初始化 ZenVault PM” | 按需安装、配置并验证 ZenTao、Obsidian 与 Project Manager 能力 | | zenvault-pull-execution | “把这个禅道执行拉到 Obsidian” | 首次创建项目，或从禅道幂等刷新已绑定项目 | | zenvault-push-execution | “预览并把这些修改推回禅道” | 对比基线，只回写受支持且经过确认的差异 | | zenvault-daily-summary | “生成指定日报的项目总结” | 根据匿名团队补充与当前项目事实更新 日报总结 | | zenvault-update | “把 ZenVault PM 升级到最新版” | 检查正式 Release，验证安装包并安全替换整套 Skills |

v0.3.2 新增量化匿名经营日报，并可自动迁移由旧开发仓库符号链接形成的 Skills 安装；整套工作流继续通过一条 npx 命令安装，不依赖 .codex-plugin。

使用 npx 安装整套 Skills

需要 Node.js 18 或更高版本。npm 自带 npx，无需单独安装 npx CLI。

npx zenvault-pm@latest install

安装器同时识别 ~/.agents/skills 和 ~/.codex/skills：已有安装只存在于其中一处时原地更新；两处都没有时，首次安装默认使用 ~/.agents/skills。它只管理以下目录：

• zenvault-setup
• zenvault-pull-execution
• zenvault-push-execution
• zenvault-daily-summary
• zenvault-update

安装器会把每个 Skill 复制为目标目录下的独立目录，而不是链接到 Git 仓库。重启或新开 Codex 会话后，直接使用 $zenvault-setup、$zenvault-pull-execution、$zenvault-push-execution、$zenvault-daily-summary 和 $zenvault-update；调用名称不带 zenvault-pm: 套件前缀。

确认安装状态：

npx zenvault-pm@latest doctor

安装已由同一 npm 包管理时，再次运行 install 会以发布包为准覆盖五个受管 Skill，并删除其中的本地差异文件；其他 Skills 不受影响。同名目录不属于 ZenVault PM 安装器时，命令会停止，只有审查后显式加入 --force 才会替换。

如果两个目录中都检测到 ZenVault PM，安装器会报告 multiple-installations，不会静默选择。审查后通过 --target 明确更新其中一处：

npx zenvault-pm@latest install --target ~/.codex/skills

安装器可识别并自动迁移旧版 ZenVault 独立副本或指向 ZenVault 仓库的开发符号链接，将其替换为受管的独立目录，因此不需要 --force。无法验证为 ZenVault 的同名目录或符号链接仍会安全停止，只有审查并明确授权后才能加入 --force。安装器不会修改未选中的目录。

固定版本、预演与自定义目标也受支持：

npx [email protected] install
npx zenvault-pm@latest install --dry-run
npx zenvault-pm@latest install --target ~/.agents/skills

[!IMPORTANT] npx 安装只负责让 Codex 发现 ZenVault PM；初始化环境才会检查并按需配置 zentao-cli、Obsidian CLI、目标 Vault 与 Project Manager。安装和升级不会读取本地账号配置、禅道数据或 Vault 内容。

从第一次拉取到日常推进

1 · 准备工作台

直接告诉 Codex：

使用 $zenvault-setup 帮我初始化执行同步需要的环境。

初始化流程会检查当前目标是否真正可用，而不比较 CLI 版本。需要的能力包括：

• zentao-cli 与可用的 ZenTao Profile；
• Obsidian 桌面应用及其 CLI；
• 目标 Vault 中已启用的 Project Manager 插件。

缺什么就只补什么。安装、登录、对话接收密码、覆盖既有配置等敏感动作都会先说明影响并等待确认。

2 · 把执行带进 Obsidian

提供一个能够定位执行的禅道链接：

使用 $zenvault-pull-execution 拉取这个执行：
https://zentao.example.test/zentao/execution-story-158.html

第一次运行会建立 Project Manager 项目；之后既可以再次提供 URL，也可以直接说：

刷新 Obsidian 中的「移动端 8 月迭代」。

一个禅道执行对应一个项目，需求成为顶层任务，需求关联任务按禅道父子关系落为子任务。重复拉取更新同一组稳定身份，不会靠标题猜测或重复建档。

拉取会把任务状态汇总为中文需求泳道：待处理、研发中、测试中、验收中、已完成、已取消。待安排、待测试、暂停开发、开发pending 和 测试pending 以受管标签补充表达，不额外创建“已阻塞”泳道。已关闭需求进入“已完成”，并展示需求创建人为负责人；若仍有未完成开发或测试任务，会保留相应 pending 标签。

3 · 在 Project Manager 中推进

你可以维护允许回写的需求与任务字段，也可以显式标记一个本地子任务“创建到禅道”。个人笔记和正文继续留在 Obsidian，不进入同步候选。

| 对象 | 可回写内容 | 明确不回写 | | --- | --- | --- | | 需求 | 标题、指派人、优先级、预计工时 | 阶段、正文、验收标准、模块 | | 任务 | 标题、类型、状态动作、指派人、优先级、预计工时、计划日期、所属需求、父任务 | 描述、备注、模块、附件 |

需求阶段不被直接改写，而是由已验证的任务状态流转推动禅道自行计算。

4 · 预览，然后推送差异

使用 $zenvault-push-execution 预览当前项目的修改，确认后推回禅道。

推送不是全量覆盖：

1. 先从 Obsidian 隐藏基线找出本地候选；
2. 只查询发生变化的需求与任务 ID；
3. 用“基线 / 本地 / 当前禅道”做三方比较；
4. 列出变更清单，经你确认后才逐项写入；
5. 仅更新已经验证成功的基线字段。

冲突默认跳过。删除任务需要独立的第二次确认；任一状态在确认后变化，原确认自动失效。完成后，Skill 会询问是否再执行一次完整拉取。

5 · 生成匿名经营日报总结

zenvault-daily-summary 只允许手动调用。提供目标日报和团队补充信息后，它会动态读取 Project Manager 的项目目录，以项目或项目组合视角直接更新 ## 日报总结：

使用 $zenvault-daily-summary 更新「30.项目/经营系统项目/进展报告/日报/2026-08-31 经营日报.md」。

补充信息：
……

姓名只用于内部匹配负责人，不会出现在生成正文。Skill 不自动刷新禅道；项目数据过旧或不完整时，会基于补充信息降级为可证实的定性总结，不猜测完成率和日期。

边界就是产品的一部分

| 原则 | ZenVault PM 的做法 | | --- | --- | | 禅道是事实源 | 不把普通 Obsidian 项目“认领”为禅道执行，也不跨执行移动对象 | | 身份先于标题 | 使用稳定的执行、需求和任务 ID；身份缺失或歧义时停止 | | 变化必须可见 | 推送前展示对象 ID、变更类型与字段，冲突不静默合并 | | 删除必须克制 | 只允许删除任务，先全 Vault 查找，再单独确认；不删除需求或执行 | | 用户内容留在本地 | 仓库、Release 与升级流程都不保存 Vault 内容、项目快照或真实配置 | | 凭据默认不外露 | 优先使用原生 Profile；外置配置只作为可选兜底，并接受权限与 Git 隔离检查；仅在用户了解风险并明确同意时接受会话输入 |

完整设计依据见架构与数据权威，字段起点见映射示例。

本地配置是可选项

原生 ZenTao Profile 与当前可用 Vault 足够时，无需创建额外配置。需要多个账号、默认 Vault 或认证兜底时，可以让 zenvault-setup 引导创建仓库之外的本地配置。

配置按以下优先级只取第一份：

1. ZENVAULT_CONFIG 指向的文件；
2. 当前工作区 .zenvault/config.yaml；
3. 用户级 zenvault-pm/config.yaml。

仓库仅提供不含真实信息的 config/zenvault.example.yaml。工作区内的真实配置必须未跟踪、未暂存、已忽略；明文凭据还必须满足当前平台的文件权限要求。schema_version 只描述配置结构，不跟随项目版本。

升级也可以用自然语言

使用 $zenvault-update 检查并升级 ZenVault PM。

升级只使用 npm 上的正式 zenvault-pm 版本，不跟随 main 或预发布版本。Skill 会先通过 npx zenvault-pm@latest check --json 展示版本和覆盖影响；确认后由同一安装器原子替换五个受管 Skill，再运行 doctor 验证。它不触碰其他 Skills、本地配置或外部 CLI。

完整契约见稳定升级策略，历史变化见版本说明。

项目地图

zenvault-pm/
├── package.json      # npm 元数据与唯一版本源
├── bin/              # npx 命令入口
├── lib/              # Standalone Skills 原子安装器
├── skills/           # 五个自包含、可组合的工作流
├── config/           # 公共依赖与无敏感信息的配置示例
├── docs/             # 架构、术语、升级策略与 Release Notes
└── scripts/          # 仓库校验、契约测试和 npm 包冒烟测试

参与开发前，在仓库根目录运行：

scripts/validate-package.sh

旧的 scripts/validate-plugin.sh 仅作为兼容入口转发到同一验证流程。

未来候选方向包括独立 Project Manager 看板和周报；每个工作流都会在边界确认后，以单一职责 Skill 的形式加入。

License

MIT · 在禅道的秩序与 Obsidian 的自由之间，留一条可控的路。