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 +0 -236
- package/README.zh-CN.md +114 -199
- package/assets/silvermoon.svg +176 -175
- package/bin/silvermoon.js +0 -0
- package/docs/assets/silvermoon-avatar.svg +395 -0
- package/docs/core-concepts.md +69 -0
- package/docs/getting-started.md +115 -0
- package/docs/maintaining.md +56 -0
- package/docs/npm-package-releases.md +139 -0
- package/docs/operations.md +110 -0
- package/docs/reference.md +138 -0
- package/docs/repository-tasks.md +61 -0
- package/package.json +69 -65
- package/schema/v1/config.schema.json +27 -24
- package/schema/v1/definitions.schema.json +30 -25
- package/schema/v1/idea-status.schema.json +44 -41
- package/schema/v1/user-config.schema.json +19 -0
- package/skills/silvermoon/SKILL.md +216 -209
- package/skills/silvermoon/references/adoption.md +122 -122
- package/src/adoption.js +313 -313
- package/src/cli.js +200 -196
- package/src/config.js +193 -176
- package/src/create-idea.js +272 -235
- package/src/git.js +284 -284
- package/src/idea-layout.js +439 -439
- package/src/idea-templates.js +109 -109
- package/src/ideas.js +140 -131
- package/src/index.js +260 -260
- package/src/language.js +29 -0
- package/src/layout.js +21 -21
- package/src/repository.js +87 -87
- package/src/user-config.js +135 -0
- package/src/whatsnext.js +453 -378
- package/src/yaml.js +66 -66
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
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
<
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
idea
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
npx
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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) — 开发检查、文档职责与发布指南。
|