Wiki 发布流程：Multica 审批触发

这是 docs-as-code 流转的"最后一公里"。

Agent / 人 写完草稿放到 drafts/ → 在 Multica 创一条 issue 走人审 → 审批通过 → 自动 promote 到 canon/ → 自动推 GitHub → wiki.86lux.net 自动更新。

全程不需要手动 git push。

---

1. 流转全图

┌──────────────────┐
│ Agent / 人写草稿 │  (wiki-compile skill / 直接编辑)
└────────┬─────────┘
         │ 写到 /opt/wiki-vault/drafts/〈rel〉.md
         │ 同时在 Multica 建 issue, 标题 = "[wiki-publish] 〈rel〉.md", 状态 = in_review
         ▼
┌──────────────────┐
│ Multica 人审     │  审批人在 multica.86lux.net 看 diff, 评论, 点同意
└────────┬─────────┘
         │ 把 issue 状态改成 done
         ▼
┌──────────────────┐
│ wiki-publisher   │  (cron 每分钟轮询 multica DB)
│ (自动)           │  - 检测到 done + 标题 [wiki-publish] + 还没 promoted marker
└────────┬─────────┘
         │ bash /opt/wiki-tools/promote.sh 〈rel〉.md
         │   1) mv drafts/〈rel〉.md → canon/〈rel〉.md
         │   2) git commit + push
         │ 然后在 issue 下追加 system comment "[wiki-publisher] promoted ..."
         │ (这条 comment 是幂等标记, 同一 issue 不会 promote 第二次)
         ▼
┌──────────────────┐
│ GitHub main      │  github.com/daishiyu1991-hub/wiki-vault
└────────┬─────────┘
         │
         │ ECS sync.sh (每 5 分钟 git pull)
         │ ECS build.sh (每 10 分钟 vitepress build)
         ▼
┌──────────────────┐
│ wiki.86lux.net   │  人/Agent 都能看
└──────────────────┘

端到端从「审批通过」到「网站上线」最长 ≈ 11 分钟（1 publisher + 5 sync + 10 build，但 sync 和 build 是错峰跑的，一般 5–10 分钟）。

---

2. 写手怎么交一份草稿

方式 A：用 wiki-compile skill（推荐，agent 自动）

agent 跑 wiki-compile skill 会自动：

1. 写到 /opt/wiki-vault/drafts/〈分类〉/〈标题〉.md
2. 在 Multica 创 issue：
   • title：[wiki-publish] 〈分类〉/〈标题〉.md（必须这个前缀，否则 publisher 不认）
   • status：in_review
   • description：包含 diff 摘要 + 来源
3. @ 你审批

方式 B：人手工交

ssh root@8.129.13.96
# 1. 写文件
vim /opt/wiki-vault/drafts/syntheses/我的新分析.md
# 2. 去 multica.86lux.net 手工建 issue
#    - title: [wiki-publish] syntheses/我的新分析.md
#    - status: 选 in_review
#    - 把文件全文贴到 description（方便审批人看）

⚠️ 标题必须严格匹配 [wiki-publish] 〈相对路径〉.md（相对 drafts/ 根的路径）。 路径只能含 [\w./\-中文]+，禁止 .. 和绝对路径。否则 publisher 会跳过并写 SKIPPED 注释。

---

3. 审批人怎么操作

1. 浏览器打开 https://multica.86lux.net
2. 切到 TeamOS workspace
3. 看 in_review 状态的 issue，标题 [wiki-publish] xxx.md
4. 在 description 里看草稿内容；如果要改：
   • 直接评论让 agent 改（agent 重写后会更新 description 或建新 issue）
   • 或者在 ECS 上直接编辑 drafts/xxx.md（不需要重新建 issue，promote 会取最新文件）
5. 觉得没问题 → 把 status 改成 done
6. 点保存

最多 1 分钟后，wiki-publisher 会自动 promote。如果想立即生效，进 ECS 跑 sudo python3 /opt/wiki-tools/wiki-publisher.py。

审批后会发生什么

• 文件从 drafts/ 移到 canon/
• GitHub 上多一个 commit：promote: 〈rel〉.md drafts -> canon
• issue 下出现 system comment：[wiki-publisher] promoted 〈rel〉.md at 〈timestamp〉
• 5–10 分钟后 wiki.86lux.net 上线

不批怎么办

直接把 status 改回 cancelled 或 backlog。禁止删 issue — publisher 是按 status + comment 幂等的，删了再建会被处理两次。

如果是已经 promote 的文件想撤回，需要管理员手动：

ssh root@8.129.13.96
git -C /opt/wiki-vault rm canon/〈rel〉.md
git -C /opt/wiki-vault -c user.name=wiki-vault-bot -c user.email=wiki-vault@86lux.net commit -m "revoke: 〈rel〉.md"
git -C /opt/wiki-vault push

---

4. 管理员速查

Publisher 在哪

• 脚本：/opt/wiki-tools/wiki-publisher.py
• Cron：* * * * * /usr/bin/python3 /opt/wiki-tools/wiki-publisher.py >> /var/log/wiki-publisher.log 2>&1
• 日志：/var/log/wiki-publisher.log
• 配置常量在脚本顶部：WORKSPACE_ID、BOT_AUTHOR_ID、DRAFTS_ROOT、PROMOTE_SCRIPT、TITLE_PREFIX

Promote 在哪

• 脚本：/opt/wiki-tools/promote.sh
• 用法：bash /opt/wiki-tools/promote.sh 〈相对路径〉.md

看最近发生了什么

tail -50 /var/log/wiki-publisher.log
git -C /opt/wiki-vault log --oneline -10
docker exec multica-postgres-1 psql -U multica -d multica -c \
  "SELECT title, status, updated_at FROM issue \
   WHERE workspace_id='cdc22470-5d78-48ba-8800-d0dde4889bd1' \
     AND title LIKE '[wiki-publish]%' \
   ORDER BY updated_at DESC LIMIT 10;"

排错

现象	原因	处理
issue done 了但没 promote	标题不匹配前缀 / 路径含 ..	看 issue 评论里的 SKIPPED 原因
promote 报错 "drafts file not found"	drafts 文件丢了	重新生成 drafts/〈rel〉.md，再次跑 publisher
GitHub 推不上去	deploy key 失效	重看 Docs-as-Code 发布架构 §部署密钥
网站不更新	sync.sh 或 build.sh cron 没跑	crontab -l 看，tail /var/log/wiki-sync.log
同一文件 promote 两次	罕见，多半是先建了 issue 又 reset comment 表	手动跑 git rm 撤回，下次别动 comment 表

Workspace ID 哪来的？

docker exec multica-postgres-1 psql -U multica -d multica -c \
  "SELECT id, name FROM workspace;"

如果以后多了 workspace 也想发 wiki，要么开多个 publisher 进程，要么把 WORKSPACE_ID 改成查所有 workspace（去掉 where 子句）。当前只挂 TeamOS。

---

5. 设计上为什么这么搞

• 不改 Multica 源码：纯外挂 + DB 轮询，Multica 后续升级不影响
• 轮询不长连接：PostgreSQL 不需要装 NOTIFY，cron 就够了，1 分钟延迟可接受
• 幂等通过 comment 标记：不在外部维护处理过的 ID 列表（重启不丢），也不动 issue 自身字段（人审视图干净）
• drafts/canon 双区：canon/ 是只读 ground truth，所有 hermes 读它；drafts/ 是 staging，hermes-admin 可写但不进知识库
• 路径约定 = 标题约定：只用 issue title 传相对路径，不需要额外 metadata，审批人也一眼就看明白要发什么

---

关联

• Docs-as-Code 发布架构 — 整套架构
• 企业版Review Gate机制 — Multica 审批怎么用
• 新成员加入指南 — 新 agent 上 hermes