silvermoon 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,236 +0,0 @@
1
- <p align="center">
2
- <img src="./assets/silvermoon.svg" width="960" alt="Silvermoon, the spirit of your project">
3
- </p>
4
-
5
- <p align="center">
6
- English | <a href="./README.zh-CN.md">简体中文</a>
7
- </p>
8
-
9
- # Silvermoon(银月)
10
-
11
- **The spirit of your project.**
12
-
13
- > *Silvermoon (银月) is named after the artifact spirit and steadfast companion
14
- > in **A Record of a Mortal's Journey to Immortality** (RMJI; 凡人修仙传).
15
- > Like her, this Silvermoon lives with the artifacts, understands their state,
16
- > and helps its companions navigate what comes next: the spirit of your
17
- > project.*
18
-
19
- Silvermoon is a shared tool for humans and agents. It checks the repository's
20
- real state, preserves facts both can understand, guards decision boundaries,
21
- and answers one question: **what's next?**
22
-
23
- It does not act as a personal assistant or make human decisions. Silvermoon
24
- belongs to the project itself, so every collaborator observes the same state
25
- and the same highest-priority next action.
26
-
27
- Silvermoon has three public commands:
28
-
29
- ```sh
30
- silvermoon whats-next [idea]
31
- silvermoon create-idea
32
- silvermoon check [--remote | --commit <revision> | --staged | --worktree]
33
- ```
34
-
35
- `whats-next` first emits a complete doctor-style adoption report and routes
36
- idea work only after every blocking requirement is satisfied. It fetches and
37
- observes but never edits, checks out, merges, commits,
38
- stashes, deletes, resets, fast-forwards, or pushes. It returns one
39
- highest-priority action. `check` validates storage and Git facts for humans,
40
- hooks, and CI. `create-idea` runs the same hygiene preflight, then creates one
41
- structured idea scaffold without staging, committing, pushing, or recording
42
- approval.
43
-
44
- ## Install
45
-
46
- ```sh
47
- npm install --save-dev silvermoon
48
- npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent github-copilot --yes --copy
49
- ```
50
-
51
- Requires Node.js 22 or newer and Git access to the configured primary branch.
52
- The npm package contains the canonical skill. Skill registration and updates
53
- belong to `npx skills`; Silvermoon only diagnoses exact content alignment and
54
- never changes the registered skill.
55
-
56
- ## Configure
57
-
58
- Create `.silvermoon/config.yaml`:
59
-
60
- ```yaml
61
- version: 1
62
- primaryRepository: https://github.com/example/repository.git
63
- primaryBranch: main
64
- ```
65
-
66
- Repository URLs are canonical credential-free HTTPS shared state. Credentials,
67
- named remotes, and URL rewrites remain local Git concerns. Metadata paths are
68
- fixed and cannot be overridden by configuration.
69
-
70
- Create or repair this file with ordinary repository editing tools. Silvermoon
71
- reports configuration findings but does not own an onboarding mutation command.
72
-
73
- ## Store Ideas
74
-
75
- Each idea is self-contained under one canonical uppercase ULID folder:
76
-
77
- ```text
78
- .silvermoon/
79
- |-- config.yaml
80
- `-- ideas/
81
- `-- 01M36QGPNTXEPP61DA4KP4AVZF/
82
- |-- status.yaml
83
- |-- ledger.md
84
- `-- outer/
85
- |-- Deployment.md
86
- `-- inner/
87
- |-- Implementation.md
88
- `-- ideal/
89
- `-- Idea.md
90
- ```
91
-
92
- The three nested worlds have canonical English and Chinese names:
93
-
94
- - **Ideal World (道心):** `Idea.md` defines the ideal.
95
- - **Inner World (内景):** `Implementation.md` defines implementation.
96
- - **Outer World (现世):** `Deployment.md` defines deployment.
97
-
98
- 道心立意,内景成形,现世验真。
99
-
100
- Every world may contain additional files or directories. Ideal World artifacts
101
- support `Idea.md`, Inner World artifacts support `Implementation.md`, and Outer
102
- World artifacts support `Deployment.md`; supporting material never replaces
103
- the canonical same-world entry.
104
-
105
- Each world is an opaque Git tree. `idealRevision` identifies `ideal/`,
106
- `implementationRevision` identifies `inner/` and therefore includes the Ideal
107
- World, and `deploymentRevision` identifies `outer/` and therefore includes both
108
- nested worlds. This creates deterministic cascading invalidation. `status.yaml`
109
- and required `ledger.md` are outside all three world trees.
110
-
111
- The Silvermoon Agent skill authors implementation and deployment plans under
112
- `## Steps` and outcome contracts under `## Acceptance criteria`. Every item
113
- uses a stable level-three `I-Sxx`, `I-ACxx`, `D-Sxx`, or `D-ACxx` heading.
114
- Each criterion contains both its observable outcome and the method that proves
115
- it. World contracts never use task-list checkboxes.
116
-
117
- The required idea-root `ledger.md` mirrors stable IDs and short titles under
118
- Implementation and Deployment Steps and Acceptance criteria checklists.
119
- Silvermoon requires the regular file but does not parse it, include it in world
120
- revisions, or infer a human decision from `[x]`. Agents update world headings
121
- and ledger entries together, reset materially changed completed items, and
122
- derive the next work from `whats-next`, the contracts, and unchecked entries.
123
-
124
- ```yaml
125
- version: 1
126
- id: 01M36QGPNTXEPP61DA4KP4AVZF
127
- alias: publish-documentation
128
- approvedRevision: 0123456789abcdef0123456789abcdef01234567
129
- implementationAcceptedRevision: 0123456789abcdef0123456789abcdef01234567
130
- deploymentAcceptedRevision: 0123456789abcdef0123456789abcdef01234567
131
- ```
132
-
133
- `version` and `id` are required. `alias` is optional; when present it is an
134
- exact, unique, case-sensitive selector. Other optional fields, in canonical
135
- order, are `abandoned: true` and the three revision fields shown above. Explicit
136
- `abandoned: false`, derived state, criteria mirrors, source locators, unknown
137
- keys, aliases/anchors, comments, and noncanonical YAML are rejected.
138
-
139
- State is derived in order:
140
-
141
- 1. `abandoned` when `abandoned: true`.
142
- 2. `preparing` when `approvedRevision` differs from `idealRevision`.
143
- 3. `implementing` when `implementationAcceptedRevision` differs from
144
- `implementationRevision`.
145
- 4. `deploying` when `deploymentAcceptedRevision` differs from
146
- `deploymentRevision`.
147
- 5. `completed` when all three revisions match.
148
-
149
- ## Navigate
150
-
151
- ```sh
152
- silvermoon whats-next
153
- silvermoon whats-next 01M36QGPNTXEPP61DA4KP4AVZF
154
- silvermoon whats-next publish-documentation --json
155
- ```
156
-
157
- Without a selector, Silvermoon asks you to choose among multiple active ideas,
158
- continue one active idea, or create a new idea. With a ULID or exact unique
159
- alias, it renders state guidance. Every invocation first checks the configured
160
- primary branch, conflicts, dirty worktree, and local/remote primary ancestry.
161
-
162
- JSON reports contain `observedPrimaryCommit`, `selectedIdea`, and exactly one
163
- `action`. They also contain `onboarding`, whose requirements carry stable IDs,
164
- statuses, blocking flags, dependencies, observed facts, structured remediation,
165
- a recommended action, and a recheck command. Execution source is
166
- `source-checkout`, `project-local`, `temporary`, `global`, or `unknown`.
167
- Temporary execution can bootstrap diagnosis; normal idea work requires the
168
- exact project dependency, installed package, and matching repository skill.
169
- Use the observed commit as the expected remote tip for later writes.
170
- If primary moves, fetch and reobserve rather than replaying a stale decision.
171
-
172
- ## Create An Idea
173
-
174
- ```sh
175
- silvermoon create-idea --json
176
- ```
177
-
178
- After branch, conflict, dirty-worktree, and primary-ancestry hygiene passes, the
179
- command generates a canonical ULID, structured `Idea.md`, `Implementation.md`,
180
- `Deployment.md`, and `ledger.md` documents, plus a canonical `status.yaml`
181
- containing only `version` and `id`. It does not require or invent an alias. The
182
- new files are intentionally untracked, so the next `whats-next <ULID>` reports
183
- `inspect-worktree-changes` until you complete the initial `Idea.md`, review the
184
- candidate, and publish it through ordinary Git. An Agent may add a concise,
185
- unique alias derived from the user's request while preparing the idea; users
186
- need not stop to name it.
187
-
188
- Silvermoon has no approval or acceptance mutation commands. After an explicit
189
- decision, edit the idea's status file, run `silvermoon check --staged`, commit
190
- the status fact, and non-force push through ordinary Git.
191
-
192
- ## Validate
193
-
194
- - `check` validates only the committed `HEAD` snapshot and reads primary
195
- coordinates from that snapshot.
196
- - `check --worktree` validates the hypothetical commit containing HEAD, the
197
- index, unstaged changes, and nonignored untracked files. It reads primary
198
- coordinates from that complete candidate.
199
- - `check --staged` validates the index snapshot.
200
- - `check --commit <revision>` validates one local commit snapshot.
201
- - `check --remote` uses committed HEAD coordinates to fetch primary, validates
202
- its immutable tip, and proves retained revision facts against complete
203
- reachable primary history.
204
-
205
- Targets are mutually exclusive and never change the caller's branch, index, or
206
- worktree. Exit status `0` means success, `1` means validation or operational
207
- failure, and `2` means invalid CLI usage. Use `--json` for the complete stable
208
- report envelope.
209
-
210
- The repository configuration schema is
211
- [schema/v1/config.schema.json](schema/v1/config.schema.json), and the idea
212
- status schema is
213
- [schema/v1/idea-status.schema.json](schema/v1/idea-status.schema.json). Both
214
- use the shared definitions in
215
- [schema/v1/definitions.schema.json](schema/v1/definitions.schema.json).
216
- Runtime checks additionally verify canonical YAML, regular fixed metadata
217
- paths, three world entries, unique aliases, current Git object format, tree
218
- object types, per-world candidate revision binding, and acceptance history.
219
-
220
- ## Adopt Silvermoon
221
-
222
- Silvermoon is a direct breaking cutover from the previous product. It recognizes
223
- only `.silvermoon/config.yaml` version 1 and does not read, convert, or diagnose
224
- previous layouts. Preserve Git history and record only acceptance facts
225
- supported by explicit review. See the installed skill's `references/adoption.md` for
226
- the adoption sequence.
227
-
228
- ## Development
229
-
230
- ```sh
231
- pnpm install --frozen-lockfile
232
- pnpm test # fast unit and repository contract tests
233
- pnpm test:integration # real filesystem and Git behavior
234
- pnpm test:e2e # packed and installed CLI behavior
235
- pnpm check # complete release-grade validation
236
- ```
package/README.zh-CN.md CHANGED
@@ -1,199 +1,114 @@
1
- <p align="center">
2
- <img src="./assets/silvermoon.svg" width="960" alt="Silvermoon,项目之灵">
3
- </p>
4
-
5
- <p align="center">
6
- <a href="./README.md">English</a> | 简体中文
7
- </p>
8
-
9
- # Silvermoon(银月)
10
-
11
- **The spirit of your project.(项目之灵。)**
12
-
13
- > *Silvermoon(银月)得名于《凡人修仙传》(A Record of a Mortal's Journey to
14
- > Immortality,RMJI)中的器灵与坚定同行者。就像她一样,这个 Silvermoon 与项目产物
15
- > 共存,理解它们的状态,并帮助同行者判断下一步:它是你的项目之灵。*
16
-
17
- Silvermoon 是人类与 Agent 共享的工具。它检查仓库的真实状态,保存双方都能理解的
18
- 事实,守护决策边界,并回答一个问题:**下一步是什么?**
19
-
20
- 它不是个人助理,也不会替人类作决定。Silvermoon 属于项目本身,因此每位协作者看到的
21
- 都是同一份状态和同一个最高优先级的下一步行动。
22
-
23
- Silvermoon 有三个公开命令:
24
-
25
- ```sh
26
- silvermoon whats-next [idea]
27
- silvermoon create-idea
28
- silvermoon check [--remote | --commit <revision> | --staged | --worktree]
29
- ```
30
-
31
- `whats-next` 先输出完整的 doctor 风格 adoption 报告;所有阻塞要求满足后才路由 idea
32
- 生命周期。它会 fetch 并观察,但绝不会编辑、checkout、merge、commit、stash、删除、
33
- reset、fast-forward 或 push;它只返回一个最高优先级行动。`check` 为人类、hook 和
34
- CI 验证存储及 Git 事实。`create-idea` 先执行同样的仓库卫生预检,再创建一个结构化
35
- idea 脚手架;它不会 stage、commit、push 或记录 approval。
36
-
37
- ## 安装
38
-
39
- ```sh
40
- npm install --save-dev silvermoon
41
- npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent github-copilot --yes --copy
42
- ```
43
-
44
- 需要 Node.js 22 或更高版本,并且能够通过 Git 访问配置的 primary branch。
45
- npm 包内包含 canonical skill;注册和更新由 `npx skills` 负责。Silvermoon 只读诊断
46
- exact content alignment,不修改 registered skill。
47
-
48
- ## 配置
49
-
50
- 创建 `.silvermoon/config.yaml`:
51
-
52
- ```yaml
53
- version: 1
54
- primaryRepository: https://github.com/example/repository.git
55
- primaryBranch: main
56
- ```
57
-
58
- 仓库 URL 是不含凭据的 canonical HTTPS 共享状态。凭据、remote 名称和 URL rewrite
59
- 仍属于本地 Git 配置。metadata 路径固定,不能通过配置覆盖。
60
-
61
- ## 存储 Idea
62
-
63
- 每个 idea 都放在一个 canonical 大写 ULID 目录中,彼此独立:
64
-
65
- ```text
66
- .silvermoon/
67
- |-- config.yaml
68
- `-- ideas/
69
- `-- 01M36QGPNTXEPP61DA4KP4AVZF/
70
- |-- status.yaml
71
- |-- ledger.md
72
- `-- outer/
73
- |-- Deployment.md
74
- `-- inner/
75
- |-- Implementation.md
76
- `-- ideal/
77
- `-- Idea.md
78
- ```
79
-
80
- 三个嵌套世界各有 canonical English name 和中文名称:
81
-
82
- - **Ideal World(道心):** `Idea.md` 定义理想。
83
- - **Inner World(内景):** `Implementation.md` 定义实现。
84
- - **Outer World(现世):** `Deployment.md` 定义部署。
85
-
86
- 道心立意,内景成形,现世验真。
87
-
88
- 每个世界都可以包含其他文件或目录。Ideal World 的产物服务于 `Idea.md`,Inner World
89
- 的产物服务于 `Implementation.md`,Outer World 的产物服务于 `Deployment.md`;
90
- 辅助材料永远不能取代同一世界的 canonical 入口。
91
-
92
- 每个世界都是不透明的 Git tree。`idealRevision` 标识 `ideal/`;`implementationRevision`
93
- 标识 `inner/`,因此包含 Ideal World;`deploymentRevision` 标识 `outer/`,因此包含
94
- 两个内层世界。由此形成确定性的级联失效。`status.yaml` 和必需的 `ledger.md` 位于
95
- 三个世界之外。
96
-
97
- Silvermoon Agent skill 在 `Implementation.md` 和 `Deployment.md` 的 `## Steps`
98
- 下编写计划,在 `## Acceptance criteria` 下编写结果契约。每项使用稳定的三级标题
99
- `I-Sxx`、`I-ACxx`、`D-Sxx` 或 `D-ACxx`。每条 criterion 同时描述可观察结果和证明
100
- 方法。世界契约不使用任务列表 checkbox。
101
-
102
- idea 根目录必需的 `ledger.md` 在 Implementation 和 Deployment 的 Steps 与
103
- Acceptance criteria checklist 中镜像稳定 ID 和短标题。Silvermoon 要求它是常规文件,
104
- 但不会解析其内容、把它纳入 world revision,或从 `[x]` 推断人类决定。Agent 同步更新
105
- world heading 与 ledger entry;若已完成事项发生实质变化,则重置 checkbox;下一步由
106
- `whats-next`、world contract 和未勾选条目共同决定。
107
-
108
- ```yaml
109
- version: 1
110
- id: 01M36QGPNTXEPP61DA4KP4AVZF
111
- alias: publish-documentation
112
- approvedRevision: 0123456789abcdef0123456789abcdef01234567
113
- implementationAcceptedRevision: 0123456789abcdef0123456789abcdef01234567
114
- deploymentAcceptedRevision: 0123456789abcdef0123456789abcdef01234567
115
- ```
116
-
117
- `version` 和 `id` 必填。`alias` 可选;存在时,它是区分大小写、精确且唯一的 selector。
118
- 其他可选字段按 canonical 顺序依次为 `abandoned: true` 和上面三个 revision 字段。
119
- 显式的 `abandoned: false`、派生 state、criteria mirror、source locator、未知 key、
120
- YAML alias/anchor、comment 以及非 canonical YAML 都会被拒绝。
121
-
122
- 状态按以下顺序派生:
123
-
124
- 1. `abandoned: true` 时为 `abandoned`。
125
- 2. `approvedRevision` 与 `idealRevision` 不同时为 `preparing`。
126
- 3. `implementationAcceptedRevision` 与 `implementationRevision` 不同时为 `implementing`。
127
- 4. `deploymentAcceptedRevision` 与 `deploymentRevision` 不同时为 `deploying`。
128
- 5. 三个 revision 全部匹配时为 `completed`。
129
-
130
- ## 导航
131
-
132
- ```sh
133
- silvermoon whats-next
134
- silvermoon whats-next 01M36QGPNTXEPP61DA4KP4AVZF
135
- silvermoon whats-next publish-documentation --json
136
- ```
137
-
138
- 不提供 selector 时,Silvermoon 会要求你从多个 active idea 中选择一个、继续唯一的
139
- active idea,或创建新 idea。提供 ULID 或精确唯一的 alias 时,它会渲染状态指引。
140
- 每次调用都会先检查配置的 primary branch、冲突、dirty worktree 以及本地与远端 primary
141
- 的 ancestry。
142
-
143
- JSON 报告包含 `observedPrimaryCommit`、`selectedIdea` 和且仅有一个 `action`。后续写入
144
- 应把 observed commit 当作预期的远端 tip。如果 primary 已移动,应重新 fetch 并观察,
145
- 而不是重放过期决定。
146
-
147
- ## 创建 Idea
148
-
149
- ```sh
150
- silvermoon create-idea --json
151
- ```
152
-
153
- branch、冲突、dirty-worktree 和 primary-ancestry 卫生检查通过后,该命令生成 canonical
154
- ULID、结构化的 `Idea.md`、`Implementation.md`、`Deployment.md`、`ledger.md`,以及只含
155
- `version` 和 `id` 的 canonical `status.yaml`。它不会要求或虚构 alias。新文件有意保持
156
- untracked,因此下一次 `whats-next <ULID>` 会报告 `inspect-worktree-changes`,直到你完成
157
- 初始 `Idea.md`、审阅 candidate,并通过普通 Git 发布。Agent 可以根据用户请求添加简洁、
158
- 唯一的 alias;用户无需为了命名而停下。
159
-
160
- Silvermoon 没有修改 approval 或 acceptance 的命令。收到明确决定后,应编辑 idea 的
161
- status 文件,运行 `silvermoon check --staged`,提交状态事实,再通过普通 Git 非强制 push。
162
-
163
- ## 验证
164
-
165
- - `check` 只验证已提交的 `HEAD` snapshot,并从该 snapshot 读取 primary coordinates。
166
- - `check --worktree` 验证由 HEAD、index、unstaged change 和未忽略 untracked file
167
- 组成的假设 commit,并从这个完整 candidate 读取 primary coordinates。
168
- - `check --staged` 验证 index snapshot。
169
- - `check --commit <revision>` 验证一个本地 commit snapshot。
170
- - `check --remote` 使用已提交 HEAD 的 coordinates fetch primary,验证其 immutable tip,
171
- 并根据完整的、可达的 primary history 证明保留的 revision fact。
172
-
173
- 这些 target 互斥,也都不会改变调用者的 branch、index 或 worktree。退出状态 `0`
174
- 表示成功,`1` 表示验证或操作失败,`2` 表示 CLI 用法无效。使用 `--json` 可获得完整、
175
- 稳定的 report envelope。
176
-
177
- 仓库配置 schema 是 [schema/v1/config.schema.json](schema/v1/config.schema.json),
178
- idea status schema 是
179
- [schema/v1/idea-status.schema.json](schema/v1/idea-status.schema.json),二者共用
180
- [schema/v1/definitions.schema.json](schema/v1/definitions.schema.json) 中的定义。
181
-
182
- 运行时检查还会验证 canonical YAML、固定常规 metadata 路径、三个 world entry、唯一
183
- alias、当前 Git object format、tree object type、逐 world candidate revision binding
184
- 和 acceptance history。
185
-
186
- ## 采用 Silvermoon
187
-
188
- Silvermoon 是从上一产品直接进行的不兼容切换。它只识别版本 1 的
189
- `.silvermoon/config.yaml`,不会读取、转换或诊断旧布局。请保留 Git history,并且只记录
190
- 有明确 review 支持的 acceptance fact。采用步骤见已安装 skill 的
191
- `references/adoption.md`。
192
-
193
- ## 开发
194
-
195
- ```sh
196
- pnpm install --frozen-lockfile
197
- pnpm check
198
- pnpm check:skills
199
- ```
1
+ <!-- markdownlint-disable-file MD041 -->
2
+
3
+ <p align="center">
4
+ <!-- markdownlint-disable-next-line MD013 -->
5
+ <img src="https://raw.githubusercontent.com/shazhou-ww/silvermoon/main/assets/silvermoon.svg" width="960" alt="Silvermoon,项目的器灵">
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="./README.md">English</a> | 简体中文
10
+ </p>
11
+
12
+ # Silvermoon(银月)
13
+
14
+ **项目的器灵。**
15
+
16
+ ## 快速开始
17
+
18
+ Silvermoon 需要 Node.js 22 或更高版本,并且能够通过 Git 访问仓库的 primary branch。
19
+
20
+ ```sh
21
+ npm install --save-dev silvermoon
22
+ npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent github-copilot --yes --copy
23
+ ```
24
+
25
+ 创建 `.silvermoon/config.yaml`:
26
+
27
+ ```yaml
28
+ version: 1
29
+ primaryRepository: https://github.com/example/repository.git
30
+ primaryBranch: main
31
+ preferredLanguage: zh-CN
32
+ ```
33
+
34
+ `preferredLanguage` 可省略。具体 idea 可以通过 `status.yaml` 的 `language`
35
+ 覆盖它,创建时也可以使用 `create-idea --language <tag>` 设置该值。否则 Silvermoon 会继续
36
+ 读取 `~/.config/silvermoon/config.yaml`,最后稳定回退到 `en-US`。
37
+
38
+ 然后创建一个 idea,让已注册的 Silvermoon skill 每次引导一个安全的下一步行动:
39
+
40
+ ```sh
41
+ npx silvermoon create-idea --json
42
+ npx silvermoon whats-next <idea> --json
43
+ ```
44
+
45
+ 在生成的 `Idea.md` 中描述想要抵达的世界,审阅并批准这个精确 revision。此后,
46
+ Silvermoon 会让目标、实现、仓库状态与现实结果始终相连。完整的首次工作流见英文
47
+ [Getting Started](./docs/getting-started.md)。
48
+
49
+ ## 为什么需要 Silvermoon
50
+
51
+ 长期运行的 Agent 工作往往让人背负太多不可见状态:有人必须记住原本想做什么、代码是否
52
+ 仍与任务一致,以及最新事实究竟留在哪次对话或哪台机器上。Silvermoon 把这些问题变成
53
+ 项目自身的一部分。
54
+
55
+ 它让人不必持续看守,只在真正属于人的决策点回来:批准目标、验收实现,以及确认结果在
56
+ 现世成立。在这些边界之间,Agent 可以检查仓库事实,并继续最高优先级的安全行动。
57
+
58
+ 它也不允许一张脱离代码的任务卡自行宣告成功。当前产物与明确决定共同派生状态,因此目标
59
+ 或实现一旦改变,依赖旧 revision 的结论自然失效。事实保存在 Git 中,工作便能跨设备、
60
+ 跨 session、跨 Agent、跨托管平台延续。
61
+
62
+ ## 项目的器灵
63
+
64
+ > 道友也不想自己的本命项目没有器灵吧?
65
+
66
+ <table>
67
+ <tr>
68
+ <td width="160" align="center" valign="top">
69
+ <!-- markdownlint-disable-next-line MD013 -->
70
+ <img src="https://raw.githubusercontent.com/shazhou-ww/silvermoon/main/docs/assets/silvermoon-avatar.svg" width="128" alt="项目器灵银月的线稿头像">
71
+ </td>
72
+ <td valign="top">
73
+ Silvermoon 得名于《凡人修仙传》中的银月。她来自灵界的银月狼族,是玲珑公主分裂出的
74
+ 两道元神之一。她在人界失去部分记忆后成为器灵,先后寄居于狼首玉如意和韩立的
75
+ 青竹蜂云剑。
76
+ <br><br>
77
+ 这个意象与项目相合:Silvermoon 不属于某位操作者或某次对话。它与项目产物共存,
78
+ 理解它们的状态,并帮助每位同行者判断下一步。人物小传只是灵感来源,不是使用工具的
79
+ 知识门槛。
80
+ </td>
81
+ </tr>
82
+ </table>
83
+
84
+ 观看《凡人修仙传》:
85
+
86
+ <!-- markdownlint-disable-next-line MD013 -->
87
+ - YouTube:[第 150 话:外海风云 26](https://www.youtube.com/watch?v=GJgezoCBIHM "《凡人修仙传》第 150 话:外海风云 26")
88
+ <!-- markdownlint-disable-next-line MD013 -->
89
+ - 哔哩哔哩:[第 150 话:外海风云 26](https://www.bilibili.com/bangumi/play/ep1231558 "《凡人修仙传》第 150 话:外海风云 26")
90
+
91
+ ## 从理想到现实
92
+
93
+ 项目不只是一张任务列表,也不是一份对话记录。它是理想经过三个嵌套世界逐渐进入现实的
94
+ 过程。
95
+
96
+ **Ideal World(道心)**确定值得追求的结果,**Inner World(内景)**让意图在仓库产物中
97
+ 成形,**Outer World(现世)**则验证这些产物在真正需要运行的地方是否成立。
98
+
99
+ > 道心立意,内景成形,现世验真。
100
+
101
+ 三个世界由内向外层层包含:实现包含它所服务的理想,部署又包含二者。这不只是比喻,也是
102
+ 工程关系。内层变化时,外层旧结论便失去原有依据,必须重新证明。
103
+
104
+ 人负责 approval 与 acceptance,Agent 负责 continuation:读取 contract、ledger 与 Git
105
+ 事实,保留并发工作,执行一个安全行动,并只在发生变化后重新观察。上下文属于项目,而不
106
+ 属于转瞬即逝的某次对话。
107
+
108
+ ## 延伸阅读
109
+
110
+ - [Getting Started](./docs/getting-started.md) — 安装、配置与第一个 idea。
111
+ - [Core Concepts](./docs/core-concepts.md) — 项目归属、三重世界、revision 与决策边界。
112
+ - [Operating Silvermoon](./docs/operations.md) — 导航、创建、发布、仓库卫生与持续推进。
113
+ - [Technical Reference](./docs/reference.md) — 存储、派生状态、CLI report、验证 target 与 schema。
114
+ - [Maintaining Silvermoon](./docs/maintaining.md) — 开发检查、文档职责与发布指南。