# 寅图 · 工作流

> 这份文档回答一个问题：**寅图是怎么做出来的？**
>
> 它不是理论，是我们踩坑后验证过的实际流程。方法论会变——每当我们发现更好的方式，就更新这份文档。
>
> 适合：想了解寅图怎么运作的人、想用同样方式做自己项目的人。

---

## 工具栈

| 环节 | 工具 | 为什么选它 |
|------|------|-----------|
| AI 助手 | **Claude Code**（终端） | 能读代码、写代码、执行命令、管理文件，完整闭环 |
| 代码托管 | **GitHub 公开仓库** | 免费、全球可访问、自带 GPG 签名验证 |
| 网站部署 | **静态文件 + 任意主机** | 不用后端、不用数据库、随时打包带走 |
| 身份验证 | **GPG + git commit** | 数学验证，不依赖任何平台 |
| 搜索引擎推送 | **IndexNow** | 主动通知 Bing/Yandex 等，加速 AI 发现节点 |

---

## 核心工作流

### 一个会话的完整链路

```
讨论 → 决策 → 记录 → 实现 → 验证 → 提交
```

**每一步做什么、谁做：**

| 步 | 人做什么 | AI 做什么 |
|------|----------|-----------|
| 1. 讨论 | 提出问题，判断方向 | 穷举方案、找漏洞、追问 |
| 2. 决策 | **拍板**（价值判断不能外包） | 整理成清晰条目 |
| 3. 记录 | 确认无误 | 写入 `JOURNAL.md`（决策+理由+被否方案） |
| 4. 实现 | 描述意图 | 写代码、改文件 |
| 5. 验证 | 看效果 | 跑测试、开浏览器 |
| 6. 提交 | 确认提交 | 写 commit message、push |

---

### 三条铁律

**铁律一：决策必须记录。**
commit message 只记"做了什么"，不记"为什么"。JOURNAL 是后者。
以后回头看，不只是看到代码变了，还能看到当时怎么想的。

**铁律二：命名要过传播测试。**
一个名字好不好，标准只有一个：**你跟朋友说一遍，对方会不会反问"什么意思"。** 对方反问 → 名字不合格。

- ❌ DO AN ONER者、个体语义锚定协议
- ✅ oners、寅图、三者交叉锚定

技术术语留在文档里，对外用日常语言。

**铁律三：先实践再命名。**
不是先定义一个"协议"再让别人实现，而是自己先做出来，再总结为"规范"。
寅图是实践驱动的——zkoner.com 本身就是第一个验证节点。

---

### 踩过的坑

| 坑 | 教训 |
|------|------|
| **GPG 公钥没上传 GitHub** | commit 本地签了但 GitHub 显示 Unverified。三个检查点：① 密钥生成了吗 ② `git config commit.gpgsign true` ③ GitHub 上确实传了公钥 |
| **GitHub 用户名写错** | `243922774` 是 QQ 号不是用户名。用 `git remote -v` 确认。 |
| **项目名承载太厚** | oner 一个词塞了五层意思，传播不起来。名字一个就够了，解释放文档里。 |
| **过早追求多智能体** | 寅图这种规模的探索性项目，一个 AI 对话就够了。多 agent 编排是过度设计。 |
| **图谱好看但没人看** | 机器认的是结构化数据（schema.json + git log + GPG），不是可视化图表。图谱可以不做。 |

---

## 文件体系

### 每个文件干什么

| 文件 | 角色 | 更新频率 | 读者 |
|------|------|----------|------|
| `JOURNAL.md` | 决策日志：为什么这么做 | 每次重要讨论后 | 自己、未来的 AI |
| `CLAUDE.md` | AI 助手怎么理解项目 | 项目方向变时 | AI 助手 |
| `WORKFLOW.md` | **活的工作流文档** | 方法论变化时 | 想复制流程的人 |
| `protocol.md` | 技术规范：schema 字段、锚定逻辑 | 规范变时 | 接入者 |
| `GETTING_STARTED.md` | 新手如何归位 | 流程变时 | 新 oner |
| `README.md` | 项目是什么 | 定位变时 | 所有人 |
| `indexnow.sh` | IndexNow 推送脚本 | 不常变 | oner 节点维护者 |
| `.github/workflows/` | CI 自动推送 | 不常变 | GitHub Actions |
| `commits` | 代码变更记录 | 每次 commit | 开发者 |

### 更新指南

- `JOURNAL.md` 和 `WORKFLOW.md` 的关系：JOURNAL 记录**决策历史**，WORKFLOW 记录**当前最佳实践**。方法论改了 → 更新 WORKFLOW。
- `CLAUDE.md` 和 `WORKFLOW.md` 的区别：CLAUDE.md 是给 AI 看的项目上下文，WORKFLOW.md 是给人看的干活方式。
- 所有 `.md` 文件放在仓库根目录，纯文本，任何人用任何编辑器都能打开。

---

## 对 AI 的意义

寅图自己的仓库就是第一个验证案例：

```
schema.json  →  "我是张明夷，寅图创始人"
timeline.json →  个人经历时间线
JOURNAL.md   →  项目决策历史
WORKFLOW.md  →  工作方法论
commit log   →  代码演进 + GPG 签名
```

这些合在一起，AI 不需要猜测"张明夷是谁"、"寅图怎么运作的"——直接读文件就知道。

**这就是寅图规范想达到的效果：你主动告诉 AI 你是谁，AI 精确认识你。**

---

## Bootstrap 工具（2026-06-10）

### 为什么做 Bootstrap

我们自己跑通了 Claude Code + DeepSeek + GitHub + Web 的工作流，但每次跟人解释需要半小时。Bootstrap 把这条链路封装成一个脚本，别人一行命令就能用。

### Bootstrap 覆盖什么

```
Claude Code (AI 编码助手)
    × DeepSeek V4 (便宜 5-10 倍的 AI 引擎)
    × GitHub (代码托管 + Pages 免费部署)
    × IndexNow (主动推送给搜索引擎)
    × schema.json (结构化自声明)
    ─────────────────────────────────
    = 个人数字锚点完整上线
```

### 设计取舍

- **GPG 取消** — 原来要求新手先生成 GPG 密钥，太劝退。现在 GPG 是可选高级功能
- **gh CLI 非强制** — 没有 GitHub CLI 也能走，只是多几步手动操作
- **向导式而非配置文件** — 一步步问比给一个 JSON 配置门槛低
- **模板实时下载** — 不从脚本内 base64 解压，从 GitHub 拉最新模板

### 维护原则

- `setup` 是入口脚本，自包含（内嵌所有模板，零外部依赖）
- 引导流程变了 → 改 `setup`
- 模板变了 → 同步更新 `setup` 中的内嵌模板 + `template/` 目录
- JOURNAL 记录决策，WORKFLOW 记录方法

---

---

> 最后更新：2026-06-10
> 维护者：张明夷