opencode-wiki-historian 0.5.1 → 0.5.3
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/dist/anchor.d.ts +63 -0
- package/dist/anchor.js +186 -0
- package/dist/lint.d.ts +19 -2
- package/dist/lint.js +73 -10
- package/dist/maintain.d.ts +44 -1
- package/dist/maintain.js +235 -1
- package/dist/migrate.js +2 -2
- package/dist/surface.d.ts +1 -1
- package/dist/surface.js +15 -1
- package/dist/templates/genres.js +3 -3
- package/dist/templates/skeletons.js +28 -18
- package/dist/tools/anchor.d.ts +10 -0
- package/dist/tools/anchor.js +90 -0
- package/dist/tools/local.js +32 -5
- package/dist/tools/shared.d.ts +3 -2
- package/dist/tools/shared.js +4 -3
- package/dist/tools.js +2 -0
- package/dist/wiki/pages.write.d.ts +6 -0
- package/dist/wiki/pages.write.js +24 -1
- package/package.json +1 -1
- package/skills/historian/SKILL.md +2 -2
- package/skills/historian/references/adapting-your-own-wiki.md +1 -1
- package/skills/historian/references/genres.md +4 -4
- package/skills/historian/references/rules.md +5 -4
package/dist/tools/local.js
CHANGED
|
@@ -8,12 +8,13 @@ import { tool } from '@opencode-ai/plugin';
|
|
|
8
8
|
import { TranslateError } from '../translate.js';
|
|
9
9
|
import { buildChronology, filterRowsByPath } from '../chronology.js';
|
|
10
10
|
import { getMap, refreshMapCache, CACHE_PATH } from '../map.js';
|
|
11
|
-
import { buildMaintainReport, renderMaintainMarkdown } from '../maintain.js';
|
|
11
|
+
import { buildMaintainReport, MAINTAIN_SCHEMA, renderMaintainMarkdown } from '../maintain.js';
|
|
12
12
|
import { buildSurfaceReport, renderSurfaceMarkdown } from '../surface.js';
|
|
13
|
+
import { lintBody, statusTokenFindings } from '../lint.js';
|
|
13
14
|
import { normalizeLocale, PathValidationError } from '../wiki/locale.js';
|
|
14
15
|
import { listPages, readPage } from '../wiki/pages.read.js';
|
|
15
16
|
import { readPrimaryNav } from '../wiki/nav.js';
|
|
16
|
-
import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
|
|
17
|
+
import { errEnvelope, isInternalPath, okJson, reportUrls, URL_MANDATE } from './shared.js';
|
|
17
18
|
const s = tool.schema;
|
|
18
19
|
const TRANSLATE_ARGS = {
|
|
19
20
|
text: s.string(),
|
|
@@ -64,6 +65,24 @@ const MAP_ARGS = {
|
|
|
64
65
|
deep: s.boolean().optional().describe('maintain: additionally read every page body (freshness + stubs + broken/stacked links + twin parity + zh-first + unfinished skeletons + claim ledgers) — one bounded read per row, cached across both scans'),
|
|
65
66
|
};
|
|
66
67
|
const MapArgsSchema = s.object(MAP_ARGS);
|
|
68
|
+
/** P1 surfacing: lint's status-token-conflict finding per scanned body,
|
|
69
|
+
* reusing runMaintain's per-page body cache (zero extra wiki reads). Machine
|
|
70
|
+
* rows carry the `status-token-conflict` key so harness graders can count it
|
|
71
|
+
* without re-deriving the rule. */
|
|
72
|
+
async function scanStatusTokenConflicts(rows, readBody, baseUrl) {
|
|
73
|
+
const out = [];
|
|
74
|
+
for (const r of rows) {
|
|
75
|
+
if (isInternalPath(r.path))
|
|
76
|
+
continue;
|
|
77
|
+
const body = await readBody(r.path, r.locale);
|
|
78
|
+
if (body === null || body === '')
|
|
79
|
+
continue;
|
|
80
|
+
const findings = statusTokenFindings(lintBody(body, { locale: r.locale, baseUrl, title: r.title }));
|
|
81
|
+
for (const f of findings)
|
|
82
|
+
out.push({ path: r.path, locale: r.locale, key: f.key, detail: f.detail });
|
|
83
|
+
}
|
|
84
|
+
return out;
|
|
85
|
+
}
|
|
67
86
|
/** maintain: light tier is map rows + ONE read-only pages.list pass per locale
|
|
68
87
|
* (the mirror's MapRow carries no tags; the list join restores the vocab view);
|
|
69
88
|
* deep additionally reads each body via readPage. Reserved-path pages (e.g.
|
|
@@ -113,15 +132,23 @@ async function runMaintain(deps, mapDeps, snapshot, deep) {
|
|
|
113
132
|
deep,
|
|
114
133
|
readBody,
|
|
115
134
|
});
|
|
135
|
+
const statusTokenConflicts = deep && readBody !== undefined
|
|
136
|
+
? await scanStatusTokenConflicts(rows, readBody, deps.options.baseUrl)
|
|
137
|
+
: [];
|
|
138
|
+
const conflictNote = statusTokenConflicts.length === 0
|
|
139
|
+
? ''
|
|
140
|
+
: `\n\n## 状态令牌冲突 Status-token conflicts (${statusTokenConflicts.length})\n` +
|
|
141
|
+
statusTokenConflicts.map((c) => `- \`${c.locale}/${c.path}\` status-token-conflict: ${c.detail}`).join('\n') +
|
|
142
|
+
'\n';
|
|
116
143
|
return {
|
|
117
144
|
action: 'maintain',
|
|
118
|
-
schema:
|
|
145
|
+
schema: MAINTAIN_SCHEMA,
|
|
119
146
|
deep: report.deep,
|
|
120
147
|
generatedAt: report.generatedAt,
|
|
121
148
|
rowCount: report.rowCount,
|
|
122
|
-
report,
|
|
149
|
+
report: { ...report, statusTokenConflicts },
|
|
123
150
|
surface,
|
|
124
|
-
markdown: `${renderMaintainMarkdown(report)}\n\n${renderSurfaceMarkdown(surface)}`,
|
|
151
|
+
markdown: `${renderMaintainMarkdown(report)}${conflictNote}\n\n${renderSurfaceMarkdown(surface)}`,
|
|
125
152
|
urls: reportUrls(deps.options.baseUrl, CACHE_PATH, 'en'),
|
|
126
153
|
};
|
|
127
154
|
}
|
package/dist/tools/shared.d.ts
CHANGED
|
@@ -129,9 +129,10 @@ export declare function sectionRefusalJson(path: string, allowedSections: readon
|
|
|
129
129
|
export declare class PublishGateError extends Error {
|
|
130
130
|
constructor(message: string);
|
|
131
131
|
}
|
|
132
|
-
/** Hard gate on front-tier writes: refuses the
|
|
132
|
+
/** Hard gate on front-tier writes: refuses the three shapes that shipped real
|
|
133
133
|
* incidents — a page claiming Active with TODO markers or empty skeleton
|
|
134
|
-
* sections,
|
|
134
|
+
* sections, a redirect stub whose body carries no clickable exit, and (R4/P1)
|
|
135
|
+
* an Active write whose table-row 状态/Status token contradicts the header.
|
|
135
136
|
* `_sandbox/*` and internal namespaces are exempt; 状态:draft stays the
|
|
136
137
|
* sanctioned work-in-progress escape hatch. Null = proceed. */
|
|
137
138
|
export declare function publishGateRefusalJson(content: string, locale: Locale, path: string, baseUrl: string): ToolResult | null;
|
package/dist/tools/shared.js
CHANGED
|
@@ -85,7 +85,7 @@ function hintFor(errorKind) {
|
|
|
85
85
|
case 'GraphQLError':
|
|
86
86
|
return 'The wiki answered a GraphQL error — check the path/locale arguments.';
|
|
87
87
|
case 'PublishGateError':
|
|
88
|
-
return '消除 TODO/空节并把状态置 Active,或保留 状态:draft 待自检通过后发布;重定向存根正文必须带可点击的 [链接](目标URL)
|
|
88
|
+
return '消除 TODO/空节并把状态置 Active,或保留 状态:draft 待自检通过后发布;重定向存根正文必须带可点击的 [链接](目标URL);Active 页的表格行 状态/Status 必须与顶部冒号状态头同 token(改状态两处一起改)。';
|
|
89
89
|
default:
|
|
90
90
|
return 'Inspect the message and retry.';
|
|
91
91
|
}
|
|
@@ -314,9 +314,10 @@ export class PublishGateError extends Error {
|
|
|
314
314
|
this.name = 'PublishGateError';
|
|
315
315
|
}
|
|
316
316
|
}
|
|
317
|
-
/** Hard gate on front-tier writes: refuses the
|
|
317
|
+
/** Hard gate on front-tier writes: refuses the three shapes that shipped real
|
|
318
318
|
* incidents — a page claiming Active with TODO markers or empty skeleton
|
|
319
|
-
* sections,
|
|
319
|
+
* sections, a redirect stub whose body carries no clickable exit, and (R4/P1)
|
|
320
|
+
* an Active write whose table-row 状态/Status token contradicts the header.
|
|
320
321
|
* `_sandbox/*` and internal namespaces are exempt; 状态:draft stays the
|
|
321
322
|
* sanctioned work-in-progress escape hatch. Null = proceed. */
|
|
322
323
|
export function publishGateRefusalJson(content, locale, path, baseUrl) {
|
package/dist/tools.js
CHANGED
|
@@ -16,6 +16,7 @@ import { makeUpdateTool, makeAppendTool } from './tools/write.js';
|
|
|
16
16
|
import { makeReadTool, makeSearchTool } from './tools/read.js';
|
|
17
17
|
import { makeTranslateSnippetTool, makeMapTool } from './tools/local.js';
|
|
18
18
|
import { makeDeleteTool, makeMoveTool, makeMigrateTool } from './tools/mutate.js';
|
|
19
|
+
import { makeAnchorTool } from './tools/anchor.js';
|
|
19
20
|
export function buildTools(opts, deps = {}) {
|
|
20
21
|
const homeDir = deps.homeDir ?? homedir();
|
|
21
22
|
// Translator must exist with NO injected deps (production plugin path):
|
|
@@ -39,5 +40,6 @@ export function buildTools(opts, deps = {}) {
|
|
|
39
40
|
historian_migrate: makeMigrateTool(toolDeps),
|
|
40
41
|
historian_delete: makeDeleteTool(toolDeps),
|
|
41
42
|
historian_move: makeMoveTool(toolDeps),
|
|
43
|
+
historian_anchor: makeAnchorTool(toolDeps),
|
|
42
44
|
};
|
|
43
45
|
}
|
|
@@ -104,6 +104,12 @@ export declare function createPage(deps: PageDeps, input: CreateInput): Promise<
|
|
|
104
104
|
/** Full read-modify-write: the mutation payload ALWAYS carries every mutable
|
|
105
105
|
* field from the read, merged with the patch (pitfalls #1 + #2). */
|
|
106
106
|
export declare function updatePage(deps: PageDeps, id: number, patch: UpdatePatch): Promise<UpdateResult>;
|
|
107
|
+
/** Splice `section` in front of the first trailer heading, keeping the
|
|
108
|
+
* trailer block last; tail-append (pre-B1 behavior) when there is none.
|
|
109
|
+
* Separators are normalized to exactly one blank line around the inserted
|
|
110
|
+
* section; the section body and the document's trailing newline are kept
|
|
111
|
+
* byte-identical. */
|
|
112
|
+
export declare function insertSectionRespectingTrailer(content: string, section: string): string;
|
|
107
113
|
export declare function appendSection(deps: PageDeps, path: string, locale: Locale, section: string): Promise<UpdateResult>;
|
|
108
114
|
export declare function movePage(deps: PageDeps, path: string, locale: Locale, newPath: string, newLocale?: Locale, confirm?: string): Promise<WriteResult>;
|
|
109
115
|
export declare function deletePage(deps: PageDeps, path: string, locale: Locale, confirm?: string): Promise<WriteResult>;
|
package/dist/wiki/pages.write.js
CHANGED
|
@@ -168,11 +168,34 @@ export async function updatePage(deps, id, patch) {
|
|
|
168
168
|
return { ...assertLocalePair(current.path, current.locale, deps.options.baseUrl), pageId: id, page };
|
|
169
169
|
}
|
|
170
170
|
// --- appendSection -----------------------------------------------------------
|
|
171
|
+
/** B1 (doctrine S9): trailer headings that must stay at the document tail.
|
|
172
|
+
* Closed set — exact heading text only (`^#{1,6}\s+<name>\s*$`), so
|
|
173
|
+
* "## References" or "## See Also:" never match. Matching is purely
|
|
174
|
+
* line-shaped; a fence-internal "## Notes" is out of scope of the spec. */
|
|
175
|
+
const TRAILER_HEADING_RE = /^#{1,6}\s+(?:Related Pages|Related pages|Related|See Also|See also|Notes|备注|相关页面|相关)\s*$/;
|
|
176
|
+
/** Splice `section` in front of the first trailer heading, keeping the
|
|
177
|
+
* trailer block last; tail-append (pre-B1 behavior) when there is none.
|
|
178
|
+
* Separators are normalized to exactly one blank line around the inserted
|
|
179
|
+
* section; the section body and the document's trailing newline are kept
|
|
180
|
+
* byte-identical. */
|
|
181
|
+
export function insertSectionRespectingTrailer(content, section) {
|
|
182
|
+
const lines = content.split('\n');
|
|
183
|
+
const trailerIdx = lines.findIndex((line) => TRAILER_HEADING_RE.test(line));
|
|
184
|
+
if (trailerIdx === -1)
|
|
185
|
+
return `${content}\n\n${section}`;
|
|
186
|
+
const before = lines.slice(0, trailerIdx);
|
|
187
|
+
const after = lines.slice(trailerIdx);
|
|
188
|
+
while (before.length > 0 && before[before.length - 1].trim() === '')
|
|
189
|
+
before.pop();
|
|
190
|
+
return before.length === 0
|
|
191
|
+
? `${section}\n\n${after.join('\n')}`
|
|
192
|
+
: `${before.join('\n')}\n\n${section}\n\n${after.join('\n')}`;
|
|
193
|
+
}
|
|
171
194
|
export async function appendSection(deps, path, locale, section) {
|
|
172
195
|
const page = await readPage(deps.client, path, locale);
|
|
173
196
|
if (page === null)
|
|
174
197
|
throw new PageNotFoundError(`page '${path}' (${locale}) does not exist`);
|
|
175
|
-
return updatePage(deps, page.id, { content:
|
|
198
|
+
return updatePage(deps, page.id, { content: insertSectionRespectingTrailer(page.content, section) });
|
|
176
199
|
}
|
|
177
200
|
// --- movePage / deletePage ----------------------------------------------------
|
|
178
201
|
export async function movePage(deps, path, locale, newPath, newLocale, confirm) {
|
package/package.json
CHANGED
|
@@ -175,9 +175,9 @@ G5 现状卡的硬约束:状态块是机读单行(`Active` / `Superseded-by:
|
|
|
175
175
|
|
|
176
176
|
1. 每页 H1 后紧跟**状态块**(见 SYN-10)
|
|
177
177
|
2. 尾部必须有 `## Related Pages` / `## 相关页面`(见 SYN-9)
|
|
178
|
-
3.
|
|
178
|
+
3. 时间线表四列:时间 | 阶段 | 事件 | 来源(见 SYN-7)
|
|
179
179
|
4. 对比表含来源列(见 SYN-6)
|
|
180
|
-
5.
|
|
180
|
+
5. 行动项表八列:措施 | 优先级 | 类型 | 负责人 | 期限 | 验证 | 跟踪 | 状态;G1 元数据表带复核期限(见 SYN-8)
|
|
181
181
|
6. 中文句 ≤20 字,英文句 ≤25 词(见 SYN-4)
|
|
182
182
|
7. ≥3 字段入表(见 SYN-5)
|
|
183
183
|
8. 禁止 `{{toc}}`、`:::` container、YAML frontmatter
|
|
@@ -38,7 +38,7 @@ Six-step self-onboarding for pointing the historian plugin at your own Wiki.js i
|
|
|
38
38
|
|
|
39
39
|
## 5. 隐私红线与发布门 / Privacy red-lines & the pre-publish gate
|
|
40
40
|
|
|
41
|
-
-
|
|
41
|
+
- 任何进入包/文档的内容不得包含:真实主机名、真实用户路径(home 目录绝对路径,如 `~/…` 展开后的形态)、token、真实私有部署的页面标题与章节表。
|
|
42
42
|
- 硬门:`node tools/privacy-audit.mjs` 扫描 `npm pack` 全部文件(含 `dist/` 与 `skills/`)。改过任何随包文本后必须跑到 exit 0 再发布。
|
|
43
43
|
|
|
44
44
|
## 6. 机构记忆层开关与证据层 / reading-loop & capture switches, evidence tier
|
|
@@ -28,13 +28,13 @@
|
|
|
28
28
|
**固定节序**:
|
|
29
29
|
|
|
30
30
|
1. 摘要 (Summary) — 3-5 句概括事件全貌
|
|
31
|
-
2. 元数据 (Metadata) —
|
|
31
|
+
2. 元数据 (Metadata) — 日期、影响范围、严重级别、关键时间(开始→发现→缓解→恢复)、发现方式、复核期限
|
|
32
32
|
3. 背景 (Background) — 事件前的系统状态
|
|
33
|
-
4. 时间线 (Timeline) —
|
|
33
|
+
4. 时间线 (Timeline) — **四列表**:时间 | 阶段 | 事件 | 来源(阶段:触发/影响/发现/缓解/恢复)
|
|
34
34
|
5. 量化影响 (Impact) — 数字说话:持续时长、影响用户数、损失
|
|
35
|
-
6. 根因 (Root Cause) — 区分直接原因 vs 根本原因;5 Whys
|
|
35
|
+
6. 根因 (Root Cause) — 区分直接原因 vs 根本原因;5 Whys;复发检查(检索同根因前例并链接或明示未见前例)
|
|
36
36
|
7. 处置 (Remediation) — 止血 vs 根治
|
|
37
|
-
8. 行动项 (Action Items) —
|
|
37
|
+
8. 行动项 (Action Items) — **八列**:措施(行内容) | 优先级 | 类型 | 负责人 | 期限 | 验证 | 跟踪 | 状态
|
|
38
38
|
9. 教训 (Lessons Learned) — 做得好 / 做错 / 侥幸
|
|
39
39
|
10. 附录 (Appendix) — 决定性摘录(每段 ≤10 行)+ 证据页链接(`_evidence/...`)+ 外部链接(commit/PR/告警)
|
|
40
40
|
11. 相关页面 (Related Pages)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# 写作规则
|
|
1
|
+
# 写作规则 24 条 (SYN-1..24)
|
|
2
2
|
|
|
3
|
-
> 跨文化 wiki 写作的通用合成规则。SYN-1..20 每条可在 `docs/research/cross-cultural-wiki-writing.md` 找到原始调研证据;SYN-21..23 为 v4 策展闭环新增,依据 `src/`
|
|
3
|
+
> 跨文化 wiki 写作的通用合成规则。SYN-1..20 每条可在 `docs/research/cross-cultural-wiki-writing.md` 找到原始调研证据;SYN-21..23 为 v4 策展闭环新增,依据 `src/` 已合入实现;SYN-24 由 G1 语料审计新增(更正注记惯例,事故复盘语料通行做法)。与既有认证可读性学说(R 系列)重叠处,语义以学说为唯一权威,本表只引用不复制(单一来源律)。
|
|
4
4
|
|
|
5
5
|
| # | 规则 | 要点 |
|
|
6
6
|
|---|------|------|
|
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
| SYN-4 | **句长约束** | 中文句 ≤20 字,英文句 ≤25 词。超过就拆句。 |
|
|
11
11
|
| SYN-5 | **表格判据** | ≥3 个字段的结构化数据用表格;≤2 字段用描述列表或行内文本。 |
|
|
12
12
|
| SYN-6 | **来源列** | 对比表与时间线表必须含「来源」列。无来源的断言不可信。 |
|
|
13
|
-
| SYN-7 |
|
|
14
|
-
| SYN-8 |
|
|
13
|
+
| SYN-7 | **时间线四列** | 事件时间线表固定四列:时间 \| 阶段 \| 事件 \| 来源。阶段取词:触发/影响/发现/缓解/恢复。缺来源列=不合格。 |
|
|
14
|
+
| SYN-8 | **行动项八列** | 行动项表八列:措施(行内容) \| 优先级 \| 类型 \| 负责人 \| 期限 \| 验证 \| 跟踪 \| 状态。优先级 P0–P2;期限列必须是 ISO 日期(YYYY-MM-DD),未定即先定日期再入表,禁止 TBD/未定——无日期项对老化清扫永久隐形;跟踪列指向 issue/页面路径,无则写 —;元数据表须带复核期限行。 |
|
|
15
15
|
| SYN-9 | **固定尾部** | 每页尾部必须有 `## Related Pages` / `## 相关页面` 节,挂至少一个真实链接到现存页面。 |
|
|
16
16
|
| SYN-10 | **状态块** | H1 后紧跟状态块:`> **Status**: Active | **Updated**: YYYY-MM-DD | **Scope**: 一行回答本页回答什么问题`。状态取值 `Active` / `Historical` / `Superseded`。中文页用 `状态`/`更新`/`范围`。 |
|
|
17
17
|
| SYN-11 | **无杂项筐** | 禁止「其他」「杂项」「Miscellaneous」节。归不进去的内容放别的页面或不放。 |
|
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
| SYN-21 | **撞车 advisory 必须响应** | `historian_page_create` 返回 `path exists — … prefer historian_page_update to amend it` 或 `疑似重复: … 先读再写` advisory(`src/tools/shared.ts` 的 `collisionAdvisory`)时,必须 `historian_read` 既有页后改用 `historian_page_update` 续写,禁止无视 advisory 直接重复建页。advisory 本身不拦截写入,拦截靠执行者响应——这是 GATE 环的设计(机器提示、人/agent 裁决)。 |
|
|
28
28
|
| SYN-22 | **Redirect 存根正文** | 存根正文只允许 `> Redirect: <canonical URL>` 一行,行首起始(`/^>\s*Redirect:/i` 判定),不携带其他正文。双语孪生各改一份(en→`/en/...`、zh→`/zh/...` canonical)。流程与 maintain 计数口径见 `references/genres.md` Redirect 存根规范。 |
|
|
29
29
|
| SYN-23 | **发布态流转** | capture 新建页必经 `状态: draft` → 十项自检通过 → `Active`。建页时自检 FAIL ≥3 条出 advisory `自检 N/10 未通过: … (不阻断, 发布前请补齐)`;FAIL 项用 `historian_page_update` 补齐后才可标 Active。禁止跳过自检直接把 draft 页改口成 Active。 |
|
|
30
|
+
| SYN-24 | **发表后更正注记** | 页面上线后修改事实(数字、日期、因果、行动项状态)须追加一行带日期的更正:`更正/Correction: YYYY-MM-DD — <改了什么、依据>`;纯排版/语法修改不触发。复盘页的行动项状态变化视为事实修改,一律适用。 |
|
|
30
31
|
|
|
31
32
|
## 来源
|
|
32
33
|
|