opencode-wiki-historian 0.6.3 → 0.7.0
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.en.md +156 -42
- package/README.md +127 -360
- package/dist/anchor.js +4 -4
- package/dist/config.d.ts +3 -3
- package/dist/config.js +3 -3
- package/dist/index.d.ts +14 -4
- package/dist/index.js +21 -52
- package/dist/lint.d.ts +2 -2
- package/dist/lint.js +2 -2
- package/dist/maintain.d.ts +2 -2
- package/dist/maintain.js +7 -7
- package/dist/map.d.ts +1 -1
- package/dist/map.js +1 -1
- package/dist/migrate-apply.d.ts +1 -1
- package/dist/migrate-apply.js +1 -1
- package/dist/migrate-score.d.ts +2 -2
- package/dist/migrate-score.js +3 -3
- package/dist/migrate-store.d.ts +1 -1
- package/dist/migrate-store.js +1 -1
- package/dist/migrate.d.ts +2 -2
- package/dist/migrate.js +2 -2
- package/dist/prompts.d.ts +20 -0
- package/dist/prompts.js +46 -0
- package/dist/skills.d.ts +33 -0
- package/dist/skills.js +88 -0
- package/dist/surface.d.ts +1 -1
- package/dist/surface.js +2 -2
- package/dist/templates/evidence.d.ts +1 -1
- package/dist/templates/evidence.js +1 -1
- package/dist/templates/genres.d.ts +5 -5
- package/dist/templates/genres.js +7 -7
- package/dist/templates/skeletons.d.ts +3 -3
- package/dist/templates/skeletons.js +3 -3
- package/dist/tools/anchor.js +2 -2
- package/dist/tools/create.js +1 -1
- package/dist/tools/local.js +1 -1
- package/dist/tools/mutate.d.ts +1 -1
- package/dist/tools/mutate.js +1 -1
- package/dist/tools/shared.d.ts +3 -3
- package/dist/tools/shared.js +10 -10
- package/dist/tools.d.ts +2 -2
- package/dist/tools.js +2 -2
- package/dist/translate.d.ts +1 -1
- package/dist/translate.js +1 -1
- package/dist/v2.d.ts +114 -0
- package/dist/v2.js +249 -0
- package/dist/wiki/assets.d.ts +1 -1
- package/dist/wiki/assets.js +1 -1
- package/dist/wiki/client.d.ts +2 -3
- package/dist/wiki/client.js +2 -3
- package/dist/wiki/locale.d.ts +1 -1
- package/dist/wiki/locale.js +3 -3
- package/dist/wiki/pages.read.d.ts +1 -1
- package/dist/wiki/pages.write.d.ts +1 -1
- package/package.json +1 -1
- package/skills/historian/SKILL.md +2 -2
package/README.en.md
CHANGED
|
@@ -1,46 +1,160 @@
|
|
|
1
1
|
# opencode-historian (English)
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> 中文文档见 [README.md](README.md) — this is the English front page.
|
|
4
|
+
|
|
5
|
+
> A bilingual wiki.js curator as an OpenCode plugin.
|
|
4
6
|
|
|
5
7
|
## What it is
|
|
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
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
8
|
+
|
|
9
|
+
One plugin that gives an OpenCode agent a curated memory layer on a Wiki.js
|
|
10
|
+
instance. Pages are written as structured, genre-typed entries.
|
|
11
|
+
Every write reports back both the English and Chinese URLs.
|
|
12
|
+
|
|
13
|
+
## Why it exists
|
|
14
|
+
|
|
15
|
+
A machine run by one human and a fleet of AI agents forgets everything.
|
|
16
|
+
Sessions end; the details scroll away. Context compresses; facts are lost.
|
|
17
|
+
|
|
18
|
+
What was deployed, what broke, what was decided — months later nobody can
|
|
19
|
+
look it up. The historian makes machine history findable again.
|
|
20
|
+
|
|
21
|
+
Its writing rules are distilled from five wiki cultures plus SRE
|
|
22
|
+
postmortem practice. The full digest lives in
|
|
23
|
+
`docs/research/cross-cultural-wiki-writing-digest.md`.
|
|
24
|
+
|
|
25
|
+
## What it does
|
|
26
|
+
|
|
27
|
+
- 11 `historian_*` tools: create, update, append, read, search, delete, move.
|
|
28
|
+
- Plus map, timeline, maintenance sweeps, migration, translation, anchoring.
|
|
29
|
+
- Genre skeletons G1–G6: incident retros, comparisons, checklists, concepts,
|
|
30
|
+
state ledgers, how-to guides.
|
|
31
|
+
- Bilingual twins (en/zh) translated automatically; you configure the engine.
|
|
32
|
+
- Every write must report two accessible URLs, en and zh.
|
|
33
|
+
- Migration gate: reformat old pages with a dry-run score first.
|
|
34
|
+
- `/historian-capture` turns the current session into an incident page.
|
|
35
|
+
|
|
36
|
+
## Quick start
|
|
37
|
+
|
|
38
|
+
1. Add the package to the `plugin` array in `opencode.jsonc`.
|
|
39
|
+
2. Set the wiki URL and the path to your API key file.
|
|
40
|
+
3. Talk naturally: "service-a OOM'd today; cache had no cap; record it."
|
|
41
|
+
|
|
42
|
+
The historian triages, picks a genre, runs its self-check, writes, and
|
|
43
|
+
returns both URLs.
|
|
44
|
+
|
|
45
|
+
```jsonc
|
|
46
|
+
["opencode-wiki-historian", {
|
|
47
|
+
"baseUrl": "http://<your-wiki>:3000",
|
|
48
|
+
"apiKeyPath": "~/.wiki-key"
|
|
49
|
+
}]
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The translation leg is optional. Unset, twins stay pending and no network
|
|
53
|
+
calls are made.
|
|
54
|
+
|
|
55
|
+
## Install
|
|
56
|
+
|
|
57
|
+
**npm (recommended).** The package is `opencode-wiki-historian`. The repo and
|
|
58
|
+
the npm name differ on purpose.
|
|
59
|
+
|
|
60
|
+
```jsonc
|
|
61
|
+
{ "plugin": ["opencode-wiki-historian"] }
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**Local path (development).** Point at a checkout; edits apply immediately.
|
|
65
|
+
|
|
66
|
+
```jsonc
|
|
67
|
+
{ "plugin": ["file:///home/<you>/workspace/opencode-historian"] }
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Verify with `opencode run --command historian --message "historian_map show"`.
|
|
71
|
+
Eleven `historian_*` tools mean success. Upgrading from v2? Disable the old
|
|
72
|
+
flat skill file first; the mapping table is in [DEVELOPMENT.md](DEVELOPMENT.md).
|
|
73
|
+
|
|
74
|
+
## Configuration
|
|
75
|
+
|
|
76
|
+
| option | default | note |
|
|
77
|
+
|---|---|---|
|
|
78
|
+
| `baseUrl` | `http://localhost:3000` | your wiki.js root |
|
|
79
|
+
| `apiKeyPath` | `~/.wikijs-api-key` | token file path |
|
|
80
|
+
| `translate.endpoint` | unset | translation API address |
|
|
81
|
+
| `translate.model` | unset | unset fails loudly on first use |
|
|
82
|
+
| `translate.apiKey` | unset | three sources, first wins |
|
|
83
|
+
| `translate.providerKey` | unset | reads a provider leg from opencode config |
|
|
84
|
+
| `sections` | `[]` (no limit) | write-prefix allowlist |
|
|
85
|
+
| `locales` | `["en","zh"]` | enabled languages |
|
|
86
|
+
| `readingLoop` | `false` | "check the wiki first" nudge |
|
|
87
|
+
| `capture.enabled` | `false` | idle reminder only |
|
|
88
|
+
|
|
89
|
+
No device model or gateway address ships inside the package. Set your own.
|
|
90
|
+
|
|
91
|
+
`sections`, when non-empty, is enforced: out-of-section writes are rejected
|
|
92
|
+
before any request is sent, naming the offending first segment.
|
|
93
|
+
|
|
94
|
+
`readingLoop` needs two signals: the option set to true, and a human-written
|
|
95
|
+
sentinel file. Either missing, it stays off; deleting the sentinel reverts
|
|
96
|
+
it instantly. An agent cannot enable it itself. Key resolution chains and
|
|
97
|
+
degradation details: see [DEVELOPMENT.md](DEVELOPMENT.md).
|
|
98
|
+
|
|
99
|
+
## Prerequisites (Wiki.js side)
|
|
100
|
+
|
|
101
|
+
The plugin never performs admin operations for you. Before installing:
|
|
102
|
+
|
|
103
|
+
- Enable namespacing; `en` and `zh` in Active Namespaces.
|
|
104
|
+
- Create an API token (Admin > API Access) covering page read/write/delete.
|
|
105
|
+
- Put the token in the `apiKeyPath` file, or in `WIKIJS_API_KEY`.
|
|
106
|
+
- Group page rules must cover your `sections` prefixes.
|
|
107
|
+
- Comments off is recommended for a knowledge base.
|
|
108
|
+
|
|
109
|
+
## Reading the Chinese pages
|
|
110
|
+
|
|
111
|
+
Chinese pages live under `/zh/<path>`; English pages have no prefix.
|
|
112
|
+
Every write result carries both URLs. If the language switcher is missing,
|
|
113
|
+
check the namespacing settings.
|
|
114
|
+
|
|
115
|
+
## Genres and the index layer
|
|
116
|
+
|
|
117
|
+
| genre | question it answers | skeleton in one line |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| G1 incident | what happened | timeline → root cause → impact → actions |
|
|
120
|
+
| G2 comparison | which one | sources + table + verdict |
|
|
121
|
+
| G3 checklist | where to start | checkable items |
|
|
122
|
+
| G4 concept | what and why | definition → diagram → examples |
|
|
123
|
+
| G5 ledger | what runs now | one row per component, with verify date |
|
|
124
|
+
| G6 runbook | how to finish a task | action + expectation + failure path |
|
|
125
|
+
|
|
126
|
+
Every write passes a 10-item self-check: short sentences, enumerations as
|
|
127
|
+
tables, timelines with a source column, both URLs reported. Full rules:
|
|
128
|
+
[DEVELOPMENT.md](DEVELOPMENT.md).
|
|
129
|
+
|
|
130
|
+
## Three content tiers
|
|
131
|
+
|
|
132
|
+
| tier | where | purpose |
|
|
133
|
+
|---|---|---|
|
|
134
|
+
| human | topic sections | distilled, bilingual, indexed |
|
|
135
|
+
| backstage | `_meta/` plus local mirror | machine bookkeeping |
|
|
136
|
+
| evidence | `_evidence/` | raw logs and transcripts; hidden from anonymous readers |
|
|
137
|
+
|
|
138
|
+
An over-long code block in a human page earns a polite advisory to move it
|
|
139
|
+
to the evidence tier. Advisories never block a write.
|
|
140
|
+
|
|
141
|
+
## Known limitations
|
|
142
|
+
|
|
143
|
+
| fact | status |
|
|
144
|
+
|---|---|
|
|
145
|
+
| Translation tools disabled when no key resolves | by design; fill config to restore |
|
|
146
|
+
| Self-evolution drivers default off; not lit on the author's machine | honest state; code and tests ready, docs do not pretend |
|
|
147
|
+
| npm name differs from repo name | `opencode-historian` was taken by an unrelated package |
|
|
148
|
+
|
|
149
|
+
## Decoupled from any machine
|
|
150
|
+
|
|
151
|
+
- No real hosts, real taxonomies, or page data ship inside.
|
|
152
|
+
- Translation address ships unset; unset means pending, never a network call.
|
|
153
|
+
- Every shipped file passes a privacy redline scan before publish; a hit
|
|
154
|
+
blocks the release.
|
|
155
|
+
- All examples are placeholders: `http://<your-wiki>:3000`, `team-notes/`.
|
|
156
|
+
|
|
157
|
+
## More
|
|
158
|
+
|
|
159
|
+
Development internals, release process, and the v2 migration map:
|
|
160
|
+
[DEVELOPMENT.md](DEVELOPMENT.md). License: MIT.
|