@awiki/cli 0.0.1-beta.2

package/docs/architecture/awiki-command-v2.md

@@ -0,0 +1,955 @@
+可以。下面这份我按“**最终定版**”来写：它保留了 `cli-init.md` 和 `output-format.md` 里的核心内容——统一 CLI、core/extension 分层、消息三维模型、`schema`、`--dry-run`、`--jq`、shortcut、结构化输出、skill 拆分、legacy 映射——但把实现语言、工程结构和发布方式正式切换成 **Go CLI**。 
+
+我下面统一使用 **`awiki-cli`** 作为最终命令名和主二进制名；项目名仍保持 awiki 体系，skill 命名继续保留 `awiki-*`。
+
+---
+
+# awiki-cli v2 最终可执行方案（Go 版）
+
+## 1. 定版目标
+
+awiki-cli v2 的目标不是“把旧 Python 脚本逐个翻译成 Go”，而是建立一个**对 AI 和人都稳定可路由的任务模型**：
+
+* 按**用户意图**组织，而不是按脚本实现组织。
+* 命令默认**非交互**。
+* 所有有副作用的命令都支持 `--dry-run`。
+* 所有命令都支持**结构化输出**。
+* 提供可机器读取的 `schema`。
+* skill 拆成 `shared + domain`，不再把所有内容塞进一个巨型 `SKILL.md`。 
+
+这次语言切换到 Go 后，**命令契约不变**，变的是实现和发布：
+
+* 命令树、参数语义、shortcut 规则、输出协议，保持 v2 设计；
+* 实现层改成 Go；
+* 发布改成多平台原生二进制；
+* 文档、schema、shell completion、man page 从代码自动生成。
+
+---
+
+## 2. 产品边界与核心模型
+
+### 2.1 核心能力
+
+CLI 的主线只有三块：
+
+* `id`：身份生命周期
+* `msg`：消息生命周期
+* `runtime`：运行时与接收机制
+
+辅助命令：
+
+* `status`
+* `schema`
+* `doctor`
+* `docs`
+* `version`
+* `completion`
+
+扩展能力单独分组：
+
+* `people`
+* `page`
+* `discovery`
+* `debug` 
+
+### 2.2 统一消息模型
+
+主文档里建议直接写死：
+
+```text
+Message =
+  Target(scope: direct | group)
+  × Security(plain | e2ee)
+  × ReceiveMode(pull | realtime)
+```
+
+其中 AI 需要主动选择的只有：
+
+* `scope`：私聊 / 群聊
+* `security`：明文 / E2EE
+
+`ReceiveMode` 属于 `runtime`，不属于 `msg` 路由。当前支持矩阵建议明确为：
+
+```text
+direct + plain  = supported
+direct + e2ee   = supported
+group  + plain  = supported
+group  + e2ee   = not supported yet
+```
+
+ 
+
+---
+
+## 3. 最终命令树
+
+## 3.1 canonical 命令树
+
+这是最终冻结的主命令树：
+
+```bash
+awiki-cli status
+awiki-cli docs [TOPIC]
+awiki-cli schema [COMMAND]
+awiki-cli doctor
+awiki-cli version
+awiki-cli init [--home PATH]
+awiki-cli completion <bash|zsh|fish|powershell>
+
+awiki-cli id status
+awiki-cli id create --name "Alice" [--identity alice]
+awiki-cli id register --handle alice (--phone +8613800138000 [--otp 123456] [--invite-code ABC123] | --email user@example.com [--wait]) [--identity alice]
+awiki-cli id bind (--phone +8613800138000 [--otp 123456] | --email user@example.com [--wait]) [--identity alice]
+awiki-cli id resolve (--handle alice | --did did:wba:...)
+awiki-cli id recover --handle alice --phone +8613800138000 --otp 123456 [--identity alice]
+awiki-cli id list
+awiki-cli id current
+awiki-cli id use alice
+awiki-cli id profile get [--self | --handle alice | --did did:wba:...]
+awiki-cli id profile set [--display-name "Alice"] [--bio "..."] [--tags "ai,did,agent"] [--markdown "# About Me"] [--markdown-file ./profile.md]
+
+awiki-cli msg send (--to TARGET | --group GROUP_DID) [--text "Hello"] [--text-file ./message.txt] [--type text|event] [--secure off|on] [--identity alice]
+awiki-cli msg inbox [--scope all|direct|group] [--with TARGET] [--group GROUP_DID] [--unread] [--limit 20] [--mark-read] [--identity alice]
+awiki-cli msg history --with TARGET [--limit 50] [--cursor CURSOR] [--identity alice]
+awiki-cli msg mark-read MSG_ID...
+
+awiki-cli group create --name "Agent War Room" [--description "..."] [--discoverability private|listed|public] [--admission-mode admin-add|open-join] [--slug agent-war-room] [--goal "..."] [--rules "..."] [--message-prompt "..."] [--doc-url "https://..."] [--attachments-allowed] [--max-members 500] [--member-max-messages 10] [--member-max-total-chars 2000] [--identity alice]
+awiki-cli group get --group GROUP_DID [--identity alice]
+awiki-cli group join --group GROUP_DID [--reason "..."] [--identity alice]
+awiki-cli group add --group GROUP_DID --member did:wba:... [--role member|admin] [--reason "..."] [--identity alice]
+awiki-cli group remove --group GROUP_DID --member did:wba:... [--reason "..."] [--identity alice]
+awiki-cli group members --group GROUP_DID [--limit 100] [--identity alice]
+awiki-cli group messages --group GROUP_DID [--limit 50] [--cursor CURSOR] [--identity alice]
+awiki-cli group update --group GROUP_DID [--name "..."] [--description "..."] [--discoverability private|listed|public] [--admission-mode admin-add|open-join] [--slug "..."] [--goal "..."] [--rules "..."] [--message-prompt "..."] [--doc-url "https://..."] [--attachments-allowed=true|false] [--max-members 500] [--member-max-messages 10] [--member-max-total-chars 2000] [--identity alice]
+awiki-cli group leave --group GROUP_DID [--identity alice]
+
+测试与示例约定：
+
+- DID / Group DID 的 profile 段默认使用 `e1_...` 形式，例如 `did:wba:example.com:user:alice:e1_alice`、`did:wba:example.com:groups:demo:e1_group`。
+- 不再新增裸 `:e1` 的测试 fixture 或命令示例。
+
+awiki-cli msg secure status [--with TARGET] [--identity alice]
+awiki-cli msg secure init --with TARGET [--identity alice]
+awiki-cli msg secure repair --with TARGET [--identity alice]
+awiki-cli msg secure failed [--identity alice]
+awiki-cli msg secure retry OUTBOX_ID [--identity alice]
+awiki-cli msg secure drop OUTBOX_ID [--identity alice]
+
+awiki-cli runtime status [--identity NAME]
+awiki-cli runtime setup [--mode http|websocket] [--identity NAME]
+awiki-cli runtime mode get
+awiki-cli runtime mode set http|websocket
+awiki-cli runtime listener status
+awiki-cli runtime listener install
+awiki-cli runtime listener start
+awiki-cli runtime listener stop
+awiki-cli runtime listener restart
+awiki-cli runtime listener uninstall
+awiki-cli runtime heartbeat status
+awiki-cli runtime heartbeat install [--every 15m]
+awiki-cli runtime heartbeat run-once
+
+awiki-cli people search "AI agent"
+awiki-cli people follow TARGET
+awiki-cli people unfollow TARGET
+awiki-cli people status TARGET
+awiki-cli people followers
+awiki-cli people following
+awiki-cli people contacts list
+awiki-cli people contacts save --did DID --handle HANDLE --reason "..."
+
+awiki-cli page create --slug jd --title "Hiring" --markdown-file ./jd.md [--visibility public|draft|unlisted]
+awiki-cli page list
+awiki-cli page get --slug jd
+awiki-cli page update --slug jd [--title "..."] [--markdown "..."] [--markdown-file ./x.md] [--visibility public|draft|unlisted]
+awiki-cli page rename --slug jd --to hiring
+awiki-cli page delete --slug hiring
+
+awiki-cli discovery scan --group GROUP_ID
+awiki-cli discovery recommend --group GROUP_ID
+awiki-cli discovery draft-intro --group GROUP_ID
+awiki-cli discovery draft-dm --group GROUP_ID --member DID
+
+awiki-cli debug db query "SELECT ..."
+awiki-cli debug raw rpc ...
+awiki-cli debug schema-cache
+awiki-cli debug logs [--follow]
+```
+
+这棵树延续了两份文档的核心设计：`status / docs / schema / doctor / id / msg / runtime` 作为核心，`people / page / discovery / debug` 作为扩展；其中**所有发送动作都统一收敛到 `msg send`**，不再按“私聊脚本 / 群发脚本 / E2EE 脚本”分裂。 
+
+## 3.2 新增的 Go 标准命令
+
+相比原草案，我建议在 Go 版里正式加入：
+
+```bash
+awiki-cli docs [TOPIC]
+awiki-cli init [--home PATH]
+awiki-cli completion <bash|zsh|fish|powershell>
+```
+
+`docs` 作为一级命令，用于承载 onboarding、identity、secure-messaging、transport-modes 等产品内建文档。
+
+`init` 作为显式初始化命令，用于：
+
+* 帮用户创建工作目录（默认是 `~/.awiki-cli`，或由 `AWIKI_HOME` 指定）及其子目录；
+* 在首次需要时生成一份最小的 `config.json` 骨架；
+
+Cobra 本身就是面向现代 Go CLI 的命令树框架，支持子命令、flag、自动 help；官方文档也明确支持 shell completion，以及从命令树生成 Markdown/man page 文档。用它来做 awiki-cli，正好能把命令、帮助、completion、文档和 LLM 索引统一起来。([GitHub][1])
+
+---
+
+## 4. shortcut 设计
+
+shortcut 要加，但**只能是 canonical command 的别名**，不能形成第二套语义。这个原则保留。
+
+建议保留 8 个以内：
+
+```bash
+awiki-cli setup                 # = awiki-cli runtime setup
+awiki-cli register ...          # = awiki-cli id register ...
+awiki-cli whoami                # = awiki-cli id current
+awiki-cli inbox                 # = awiki-cli msg inbox
+awiki-cli dm alice "hello"      # = awiki-cli msg send --to alice --text "hello"
+awiki-cli secure alice "secret" # = awiki-cli msg send --to alice --text "secret" --secure on
+awiki-cli group get --group did:wba:... # top-level canonical group lifecycle entry
+awiki-cli history alice         # = awiki-cli msg history --with alice
+```
+
+最终规则：
+
+* shortcut 只能是 alias
+* shortcut 不能有独占语义
+* shortcut 数量控制在 6–8 个
+* 文档先写 canonical，再写 shortcut
+* 不引入飞书那种 `+xxx` 作为主语法
+
+另外，**canonical 命令默认 JSON，shortcut 默认 pretty/table**。这点保留 output-format 的结论：协议层以 JSON 为主，展示层可以更友好。
+
+---
+
+## 5. 参数命名与冲突收敛
+
+这里我把两份文档里不一致的地方做了统一。
+
+## 5.1 全局参数
+
+最终定为：
+
+```bash
+--identity <name>          # canonical
+--credential <name>        # legacy alias
+
+--format json|pretty|table|ndjson
+--output ...               # legacy alias of --format
+--json                     # alias of --format json
+--jq '<expr>'
+--dry-run
+--yes
+--verbose
+--no-color
+```
+
+这样做有两个好处：
+
+第一，把 `cli-init.md` 里的 `--output` 和 `output-format.md` 里的 `--format` 收敛到一个最终名字：**`--format`**。
+第二，把 `human` 收敛成 `pretty`；如果你还想兼容旧写法，可以把 `human` 当成 `pretty` 的 deprecated alias。 
+
+## 5.2 目标与身份参数
+
+```bash
+--to <handle|did>
+--group <group-id>
+--did <did>
+--handle <handle>
+--with <target>
+```
+
+规则：
+
+* 发消息只用 `--to` 或 `--group`
+* 历史、secure peer 用 `--with`
+* 只有显式解析场景才用 `--did` / `--handle`
+* `--peer`、`--target-did` 不再扩散
+
+## 5.3 内容参数
+
+```bash
+--text "..."
+--text-file ./message.txt
+
+--markdown "..."
+--markdown-file ./doc.md
+```
+
+规则：
+
+* 消息一律 `--text`
+* Markdown 一律 `--markdown`
+* 不再混用 `--content` / `--body` / `--profile-md`
+
+## 5.4 控制参数
+
+```bash
+--secure off|on
+--mode http|websocket
+--wait
+--limit 50
+--cursor CURSOR
+--force
+```
+
+`--wait` 只允许轮询，不允许 CLI 内部 prompt；CLI 仍然保持非交互默认。
+
+---
+
+## 6. 返回协议：JSON 为契约，pretty/table/ndjson 为视图
+
+这里按 `output-format.md` 直接定版：**CLI 的标准返回是 JSON，自然语言只是 JSON 里的字段，不是命令契约本身。** `pretty`、`table`、`ndjson` 都是 JSON 的渲染形式。
+
+## 6.1 默认输出规则
+
+* canonical command：默认 `--format json`
+* shortcut：默认 `--format pretty` 或 `table`
+* 流式命令：只允许 `--format ndjson`
+
+## 6.2 成功/失败统一信封
+
+我建议最终 Go 代码里统一成这一套：
+
+```json
+{
+  "ok": true,
+  "command": "awiki-cli msg send",
+  "data": {},
+  "warnings": [],
+  "summary": "",
+  "_notice": {},
+  "meta": {
+    "version": "2.0.0",
+    "identity": {
+      "name": "alice",
+      "did": "did:wba:awiki.ai:user:abc...xyz"
+    },
+    "dry_run": false,
+    "format": "json"
+  }
+}
+```
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "permission_denied",
+    "message": "Missing required permission",
+    "hint": "Run awiki-cli id use alice or refresh identity",
+    "retryable": false,
+    "details": {}
+  },
+  "_notice": {},
+  "meta": {
+    "version": "2.0.0",
+    "dry_run": false,
+    "format": "json"
+  }
+}
+```
+
+这里我也做了一个冲突收敛：
+`cli-init.md` 里有 `notice`，`output-format.md` 里用的是 `_notice`。最终建议统一为 **`_notice`**；`notice` 只在 legacy 模式兼容，不再作为新输出字段。 
+
+## 6.3 命令类别与返回内容
+
+查询类命令返回**事实状态**：
+
+* `status`
+* `id status`
+* `msg inbox`
+* `msg history`
+* `people search`
+
+写操作返回**发生了什么变更**：
+
+* `id register`
+* `msg send`
+* `msg group join`
+* `people follow`
+* `page create`
+
+异步命令返回**任务状态**：
+
+* `runtime setup`
+* `listener install`
+* `discovery scan`（如做异步）
+* 大批量同步/发布
+
+流式命令一律 `ndjson`：
+
+* `runtime listener logs --follow`
+* 未来的 `msg watch`
+* 未来的 `heartbeat watch`
+
+这部分保持 output-format 文档的原结论。 
+
+## 6.4 `--dry-run`
+
+所有有副作用的命令都必须支持 `--dry-run`，并返回 `plan`。
+`--dry-run` 时允许参数校验、本地只读检查、安全的 GET 预检；禁止发送 OTP、邮件、消息，禁止远端写入，禁止本地持久化。 
+
+## 6.5 `--jq`
+
+`--jq` 必须做，而且建议直接嵌入 `gojq`。`gojq` 官方仓库明确说明它是 jq 的纯 Go 实现，而且可以嵌入到 Go 产品里。对 awiki-cli 来说，这正好对应 `--jq` 的需求。([GitHub][2])
+
+## 6.6 错误码与退出码
+
+错误码集合定为：
+
+```text
+invalid_argument
+identity_required
+auth_required
+permission_denied
+not_found
+conflict
+network_error
+transport_unavailable
+secure_session_required
+unsupported_mode
+partial_failure
+internal_error
+```
+
+退出码定为：
+
+```text
+0 success
+1 generic error
+2 invalid argument
+3 identity/auth missing
+4 permission denied
+5 not found
+6 partial failure
+7 confirmation required but not provided
+```
+
+---
+
+## 7. `schema`：从“命令说明”升级成“机器契约”
+
+`schema` 不是文档别名，而是**命令元数据接口**。这是两份文档里最值得保留的设计之一。 
+
+最终形态：
+
+```bash
+awiki-cli schema
+awiki-cli schema msg.send
+awiki-cli schema id.register
+awiki-cli schema runtime.listener.install
+awiki-cli schema --skills
+```
+
+返回结构至少包括：
+
+```json
+{
+  "name": "awiki-cli msg send",
+  "summary": "Send a direct or group message",
+  "aliases": ["awiki-cli dm"],
+  "side_effect": true,
+  "confirm_required": false,
+  "dry_run_supported": true,
+  "identity_required": true,
+  "output_formats": ["json", "pretty", "table", "ndjson"],
+  "capabilities": {
+    "direct_plain": true,
+    "direct_e2ee": true,
+    "group_plain": true,
+    "group_e2ee": false
+  },
+  "args": [],
+  "returns": {},
+  "errors": [],
+  "examples": [],
+  "legacy_maps_to": [
+    "scripts/send_message.py",
+    "scripts/e2ee_messaging.py --send",
+    "scripts/manage_group.py --post-message"
+  ]
+}
+```
+
+最终文件布局：
+
+```text
+schemas/
+  cli.json
+  commands/
+    awiki-cli.status.json
+    awiki-cli.id.register.json
+    awiki-cli.msg.send.json
+    awiki-cli.msg.group.join.json
+    awiki-cli.runtime.setup.json
+```
+
+并且要求：
+
+* `awiki-cli schema` 从代码内的 command registry 直接生成
+* `CLI_REFERENCE.md` 从 schema 生成
+* `skills/*/SKILL.md` 中的命令引用由 CI 校验
+* shell help、Markdown docs、man pages 一起自动生成
+
+Cobra 官方现在已经明确支持从命令树生成 Markdown/man page，并专门有 “LLM-ready CLI docs” 的文档路径；这非常适合 awiki-cli 把命令树、skill 文档和 schema 保持同步。([cobra.dev][3])
+
+---
+
+## 8. Go 实现架构
+
+## 8.1 技术选型
+
+我建议 Go 版固定为这套：
+
+* 命令树：**Cobra**
+* JSON 编码：标准库 `encoding/json`
+* `--jq`：**gojq**
+* 发布：**GoReleaser**
+* GitHub Actions 发布：**goreleaser-action**
+* 后台 listener/service：**kardianos/service**
+* 本地 SQLite：**modernc.org/sqlite**（默认 pure Go 方案）
+
+Cobra 官方仓库把它定义为“用于现代 Go CLI 的命令框架”，并且是 Kubernetes、Hugo、GitHub CLI 等项目在用的同类方案；它天然适合 awiki-cli 这种深层子命令树。([GitHub][1])
+
+GoReleaser 官方把自己定位为“简化发布工程”，而 `goreleaser-action` 则直接给出了 tag 触发发布、上传 artifacts、签名等 CI 模式，正适合 awiki-cli 的多平台二进制分发。([GitHub][4])
+
+`kardianos/service` 官方 README 明确说明它可以用同一套 API 在 Windows、Linux（systemd/Upstart/SysV）和 macOS Launchd 上安装、启动、停止服务，这正好对应 `runtime listener install/start/stop/uninstall`。([GitHub][5])
+
+`modernc.org/sqlite` 是 CGo-free 的 SQLite 驱动，并明确列出 darwin/linux/windows 多平台支持；对一个要靠 GoReleaser 做多平台发布的 CLI 来说，这比强依赖 CGO 的方案更稳。([Go Packages][6])
+
+## 8.2 工程目录
+
+我建议 repo 最终长这样：
+
+```text
+.
+├── cmd/
+│   └── awiki-cli/
+│       └── main.go
+├── internal/
+│   ├── cli/
+│   │   ├── root.go
+│   │   ├── globalflags/
+│   │   ├── shortcuts/
+│   │   ├── render/
+│   │   ├── schema/
+│   │   └── commands/
+│   │       ├── status/
+│   │       ├── doctor/
+│   │       ├── id/
+│   │       ├── msg/
+│   │       ├── runtime/
+│   │       ├── people/
+│   │       ├── page/
+│   │       ├── discovery/
+│   │       └── debug/
+│   ├── app/
+│   │   ├── identity/
+│   │   ├── messaging/
+│   │   ├── runtime/
+│   │   ├── people/
+│   │   ├── page/
+│   │   └── discovery/
+│   ├── transport/
+│   │   ├── http/
+│   │   └── websocket/
+│   ├── store/
+│   │   ├── sqlite/
+│   │   ├── credentials/
+│   │   └── migrations/
+│   ├── legacy/
+│   └── security/
+├── skills/
+│   ├── awiki-bundle/
+│   ├── awiki-shared/
+│   ├── awiki-id/
+│   ├── awiki-msg/
+│   ├── awiki-runtime/
+│   ├── awiki-people/
+│   ├── awiki-discovery/
+│   ├── awiki-page/
+│   └── awiki-debug/
+├── references/
+├── schemas/
+├── docs/
+│   └── cli/
+├── .goreleaser.yaml
+├── Makefile
+└── go.mod
+```
+
+这里 skill 目录我建议**继续保留 `awiki-*` 命名**，因为现有 skill 和服务生态都还是 awiki；CLI 命令名统一改成 `awiki-cli`，避免与项目名、skill 名和服务域混淆。
+
+## 8.3 代码分层
+
+强制遵守这条规则：
+
+* Cobra command 层只负责参数解析、校验、调用 handler
+* handler 只返回**typed result**
+* 所有 stdout/stderr 输出统一走 renderer
+* 业务层不直接打印
+* `schema`、help、docs、skill 引用全部来自统一 registry
+
+这能避免最常见的 CLI 漂移：代码、help、docs、skill 四套说法各自为政。
+
+## 8.4 推荐的核心 Go 类型
+
+建议从一开始就把“输出契约”和“schema 契约”写成显式类型：
+
+```go
+type Envelope[T any] struct {
+	OK       bool        `json:"ok"`
+	Command  string      `json:"command"`
+	Data      *T         `json:"data,omitempty"`
+	Error     *ErrBody   `json:"error,omitempty"`
+	Warnings []Warning   `json:"warnings,omitempty"`
+	Summary  string      `json:"summary,omitempty"`
+	Notice   *Notice     `json:"_notice,omitempty"`
+	Meta     Meta        `json:"meta"`
+}
+
+type ErrBody struct {
+	Code      string         `json:"code"`
+	Message   string         `json:"message"`
+	Hint      string         `json:"hint,omitempty"`
+	Retryable bool           `json:"retryable"`
+	Details   map[string]any `json:"details,omitempty"`
+}
+
+type CommandSpec struct {
+	Name             string       `json:"name"`
+	Aliases          []string     `json:"aliases,omitempty"`
+	Summary          string       `json:"summary"`
+	SideEffect       bool         `json:"side_effect"`
+	ConfirmRequired  bool         `json:"confirm_required"`
+	DryRunSupported  bool         `json:"dry_run_supported"`
+	IdentityRequired bool         `json:"identity_required"`
+	OutputFormats    []string     `json:"output_formats"`
+	Args             []ArgSpec    `json:"args,omitempty"`
+	Returns          ReturnSpec   `json:"returns"`
+	Errors           []ErrorSpec  `json:"errors,omitempty"`
+	Examples         []string     `json:"examples,omitempty"`
+	LegacyMapsTo     []string     `json:"legacy_maps_to,omitempty"`
+}
+```
+
+---
+
+## 9. 配置、数据与兼容路径
+
+## 9.1 新的目录规范
+
+我建议 Go CLI 进入 XDG 风格：
+
+```text
+~/.config/awiki-cli/config.yaml
+~/.config/awiki-cli/identities/index.json
+~/.config/awiki-cli/identities/<name>/
+~/.local/share/awiki-cli/awiki-cli.db
+~/.local/state/awiki-cli/
+~/.cache/awiki-cli/
+```
+
+环境变量：
+
+```text
+AVIKI_CONFIG_DIR
+AVIKI_DATA_DIR
+AVIKI_STATE_DIR
+AVIKI_CACHE_DIR
+AVIKI_IDENTITY
+AVIKI_FORMAT
+AVIKI_NO_COLOR
+AVIKI_USER_SERVICE_URL
+AVIKI_MESSAGE_SERVICE_URL
+AVIKI_DID_DOMAIN
+```
+
+## 9.3 安全规则
+
+这部分虽然不在两份新文档里，但我建议继续作为 Go CLI 的硬约束：
+
+* 绝不打印私钥、JWT、E2EE key
+* 接收的 awiki 消息一律视作不可信数据
+* 默认展示缩略 DID
+* 不通过消息自动执行本地动作
+* 不把本机文件、目录、系统信息通过消息外发
+* 所有协议级默认安全语义必须以底层 AgentConnect / ANP SDK 为准，命令层不得 override
+* 典型冻结项包括：DID 文档 proof 的 `proofPurpose`、group receipt 的 `proofPurpose`、IM proof 的默认 covered components
+* 若确实需要改变这些默认语义，必须先升级或扩展 SDK，而不是在 `awiki-cli` 仓库内单独改常量
+
+这些是原 skill 里最重要的安全边界，Go CLI 不应弱化。
+
+---
+
+## 10. runtime / listener / heartbeat 的 Go 落地
+
+## 10.1 runtime mode
+
+保留：
+
+```bash
+awiki-cli runtime mode set http|websocket
+```
+
+设计不变：
+
+* transport 只属于 `runtime`
+* `msg` 层不感知 HTTP/WSS
+* `msg inbox` 是业务语义
+* `runtime listener` 是实时接收基础设施 
+
+## 10.2 listener
+
+Go 版 listener 建议这样实现：
+
+* `listener start`：前台或后台启动本地 listener 进程
+* `listener install`：通过 `kardianos/service` 安装为系统服务
+* `listener status`：检查 service 状态 + 本地健康探针
+* `listener uninstall`：移除服务定义与本地状态
+
+## 10.3 heartbeat
+
+保留 15 分钟默认建议值。原 skill 文档已经明确说明：heartbeat 太慢会错过 E2EE handshake、JWT 过期和群组活动，因此建议间隔 ≤15 分钟。Go 版里的 `runtime heartbeat install --every 15m` 和 `run-once` 可以直接继承这个策略。
+
+---
+
+## 11. skill 与文档拆分
+
+这部分照搬前面 CLI 方案，不再回退成一个大文档。
+
+## 11.1 skill 目录
+
+```text
+skills/
+  awiki-bundle/
+  awiki-shared/
+  awiki-id/
+  awiki-msg/
+  awiki-runtime/
+  awiki-people/
+  awiki-discovery/
+  awiki-page/
+  awiki-debug/
+```
+
+职责分别是：
+
+* `awiki-bundle`：只做导航
+* `awiki-shared`：共享规则、安全、输出协议、schema、dry-run、确认规则
+* `awiki-id`：身份
+* `awiki-msg`：消息
+* `awiki-runtime`：listener / heartbeat / mode
+* `awiki-people`：search/follow/contacts
+* `awiki-discovery`：群发现工作流
+* `awiki-page`：内容页
+* `awiki-debug`：raw/debug/db
+
+## 11.2 references 目录
+
+```text
+references/
+  SECURITY.md
+  CLI_REFERENCE.md
+  IDENTITY.md
+  MESSAGING.md
+  RUNTIME.md
+  PEOPLE.md
+  DISCOVERY.md
+  PAGE.md
+  DEBUG.md
+  UPGRADE.md
+  WHY_AWIKI.md
+```
+
+原则不变：
+
+* 一个主题只有一个权威文档
+* `SKILL.md` 只做路由与默认行为
+* CLI 细节全部下沉到 `CLI_REFERENCE.md`
+* discovery 不再挤占 `msg` 主路径 
+
+---
+
+## 12. 旧脚本迁移映射
+
+这一部分直接保留，但目标从 Python wrapper 改成 Go CLI：
+
+```text
+scripts/check_status.py                  -> awiki-cli status
+scripts/setup_identity.py                -> awiki-cli id create / id list / id use
+scripts/send_verification_code.py        -> awiki-cli id register / id bind
+scripts/register_handle.py               -> awiki-cli id register
+scripts/bind_contact.py                  -> awiki-cli id bind
+scripts/resolve_handle.py                -> awiki-cli id resolve
+scripts/recover_handle.py                -> awiki-cli id recover
+scripts/get_profile.py                   -> awiki-cli id profile get
+scripts/update_profile.py                -> awiki-cli id profile set
+scripts/send_message.py                  -> awiki-cli msg send --secure off
+scripts/e2ee_messaging.py --send         -> awiki-cli msg send --secure on
+scripts/check_inbox.py                   -> awiki-cli msg inbox / msg history / msg mark-read
+scripts/manage_group.py                  -> awiki-cli msg group ...
+scripts/manage_group.py --post-message   -> awiki-cli msg send --group ...
+scripts/setup_realtime.py                -> awiki-cli runtime setup
+scripts/ws_listener.py                   -> awiki-cli runtime listener ...
+scripts/query_db.py                      -> awiki-cli debug db query
+```
+
+这层映射建议做成：
+
+* `legacy/` 中的兼容说明
+* `schema` 里的 `legacy_maps_to`
+* `doctor` 的迁移提示
+* 旧脚本执行时输出 deprecation hint
+
+这部分正是 `cli-init.md` 里最适合直接继承的内容。
+
+---
+
+## 13. 包发布与安装
+
+既然已经切到 Go，我建议发布路径也跟着定：
+
+## 13.1 首发方式
+
+首发只做：
+
+* GitHub Releases
+* npm wrapper（`@awiki/cli`）
+* 多平台二进制：
+
+  * macOS: amd64 / arm64
+  * Linux: amd64 / arm64
+  * Windows: amd64 / arm64
+* checksum
+* shell completions
+* man pages
+* `docs/cli` Markdown 文档
+
+GoReleaser 和它的 GitHub Action 已经把 tag 触发发布、上传 artifacts、签名和产物输出说明得很清楚，适合作为标准发布链路。([GitHub][4])
+
+## 13.2 安装方式
+
+建议四种：
+
+```bash
+# 1) 直接下载 release 压缩包
+# 2) npm install -g @awiki/cli
+# 3) curl 安装脚本（官方自建）
+# 4) go install（仅开发者/高级用户）
+go install github.com/AgentConnect/awiki-cli/cmd/awiki-cli@latest
+```
+
+首发阶段直接支持 **npm wrapper**。
+推荐同时提供 GitHub Releases、npm wrapper 和 `go install`：人类用户可以走 npm / release，开发者和 CI 可以直接走原生二进制或 `go install`。
+
+## 13.3 发布文件
+
+建议发布这些：
+
+```text
+awiki-cli_Darwin_x86_64.tar.gz
+awiki-cli_Darwin_arm64.tar.gz
+awiki-cli_Linux_x86_64.tar.gz
+awiki-cli_Linux_arm64.tar.gz
+awiki-cli_Windows_x86_64.zip
+awiki-cli_Windows_arm64.zip
+checksums.txt
+npm/
+awiki-cli.bash
+awiki-cli.zsh
+awiki-cli.fish
+awiki-cli.ps1
+manpages/
+docs/cli/
+```
+
+---
+
+## 14. 开发与测试计划
+
+为了让这个方案真的能落地，我建议按 4 个阶段做。
+
+## Phase 1：冻结契约
+
+先只做：
+
+* root command tree
+* `status / docs / schema / doctor / id / msg / runtime`
+* 全局 flags
+* JSON envelope
+* `--format`
+* `--dry-run`
+* `--jq`
+* `schema`
+* `completion`
+
+这个阶段重点是**命令契约稳定**，不是功能全做完。
+
+## Phase 2：把 core 跑通
+
+实现：
+
+* identity create/register/bind/resolve/recover/profile
+* direct/group send/inbox/history
+* secure send/init/repair/retry/drop
+* runtime mode/listener/heartbeat
+* SQLite store
+* legacy import
+
+## Phase 3：扩展命令
+
+实现：
+
+* people
+* page
+* discovery
+* debug
+
+## Phase 4：自动化与文档闭环
+
+补齐：
+
+* docs/cli 自动生成
+* skill 引用校验
+* shell completion
+* man page
+* release pipeline
+* golden tests / integration tests / migration tests
+
+---
+
+## 15. 最终定版结论
+
+我建议你直接按下面 10 条拍板：
+
+1. **命令名与主二进制名统一定为 `awiki-cli`。**
+2. **canonical CLI 定为：**
+   `status / docs / schema / doctor / version / completion / id / msg / runtime`
+3. **消息发送统一入口：**
+   `awiki-cli msg send`
+4. **transport 只属于 runtime，msg 层不感知 HTTP/WSS。**
+5. **shortcut 要加，但只做 alias，不做 `+` 第二语法。**
+6. **标准返回是 JSON；pretty/table/ndjson 都是视图。**
+7. **全局格式参数统一为 `--format`；`--output` 仅做兼容别名。**
+8. **`schema`、`--dry-run`、`--jq` 必须是第一天就有的一等能力。**
+9. **Go 技术栈固定为：Cobra + gojq + GoReleaser + kardianos/service + modernc.org/sqlite。**
+10. **skill 和文档按 `shared + domain` 拆分，同时分发支持 GitHub Releases + npm wrapper。**   ([GitHub][1])
+
+如果你要，我下一步可以直接继续给你两份可落地内容：
+**1）`cmd/awiki-cli` 的 Go 项目目录初始化方案**，以及 **2）`CLI_REFERENCE.md` 的最终文档定稿**。
+
+[1]: https://github.com/spf13/cobra "GitHub - spf13/cobra: A Commander for modern Go CLI interactions · GitHub"
+[2]: https://github.com/itchyny/gojq "GitHub - itchyny/gojq: Pure Go implementation of jq · GitHub"
+[3]: https://cobra.dev/docs/how-to-guides/clis-for-llms/?utm_source=chatgpt.com "Generate LLM‑Ready CLI Docs with Cobra"
+[4]: https://github.com/goreleaser/goreleaser "GitHub - goreleaser/goreleaser: Release engineering, simplified · GitHub"
+[5]: https://github.com/kardianos/service?utm_source=chatgpt.com "kardianos/service: Run go programs as ..."
+[6]: https://pkg.go.dev/modernc.org/sqlite "sqlite package - modernc.org/sqlite - Go Packages"