@sanqianx/project-knowledge 5.0.9-rc.9 → 5.0.10-rc.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "project-knowledge",
-      "version": "5.0.9-rc.9",
+      "version": "5.0.10-rc.1",
       "source": "./plugins/project-knowledge",
       "description": "Search durable project decisions and implementation history through MCP."
     }

package/CHANGELOG.md

@@ -1,5 +1,145 @@
 # Changelog
 
+## [5.0.10-rc.1] - 2026-10-12
+
+- Add global/domain/project memory applicability and a single review form for
+  editing content, selecting any existing target and confirming atomically.
+- Retain original evidence, scope-aware duplicate suppression, existing v5
+  global memories and all fixed code/knowledge directory bindings.
+- Filter exclusive memories before retrieval ranking and file reads; clear old
+  projections after scope changes and report/retry pending file synchronization.
+- Keep the accepted Workbench, vector-hub and event-bridge versions unchanged;
+  candidate package acceptance precedes stable latest promotion.
+
+## [5.0.9] - 2026-10-12
+
+- Freeze the accepted rc.19 web runtime and exact module versions; no new
+  product features, old-version migration or existing v5 data reset.
+- Include index failure diagnostics, index-only recovery, knowledge-root
+  index storage, safe client discovery/notify chaining, maintenance isolation
+  and the embedded Workbench startup/streaming fixes from the candidate series.
+- Publish initially to next. Official npm installation, Node 22/24 regression,
+  real MiniMax knowledge/embedding loops and existing-user upgrade acceptance
+  must pass before stable latest promotion.
+
+## [5.0.9-rc.19] - 2026-10-12
+
+- Pin Workbench 0.13.2-rc.7. Startup shows a loading state and keeps controls
+  inert until projects and event handlers are ready; the existing streaming
+  and session recovery paths are unchanged.
+- Preserve the real rc.18 premature-click failure and require its actual
+  usable-page ready receipt in browser acceptance. Add a deterministic
+  startup gate regression and Node 22/24 retests.
+- Include Windows test-server cleanup hardening and corrected storage-root
+  assertions. Retain existing v5 data, third-party configuration and the
+  official-package acceptance gate before stable latest promotion.
+
+## [5.0.9-rc.18] - 2026-10-12
+
+- Project resolution for MCP and CLI now reports the vector-hub storage root
+  selected in settings, not the retired shell database path. A running tool
+  rereads root changes; resolution does not move files or rebuild indexes.
+- Preserve the reproduced rc.17 diagnostic mismatch and add Node 22/24
+  coverage for configured, changed and unset roots and MCP output.
+- Retain existing v5 data and all accepted module pins. Publish to next;
+  stable latest remains behind official-package and actual-user acceptance.
+
+## [5.0.9-rc.17] - 2026-10-11
+
+- Pin Workbench 0.13.2-rc.6. Repeated embedded notifications for the current
+  project no longer abandon a newly created session; real project changes and
+  late project lookups still preserve isolation and per-project drafts.
+- Keep a healthy progress stream labelled as connected on redundant online
+  events. Verify actual offline cleanup, snapshot recovery and exactly one
+  restored SSE connection with a real browser and HTTP proxy.
+- Preserve the rc.16 real Workbench failure and require official-package
+  streaming/citation acceptance before upgrading the actual user instance.
+- No data reset or third-party configuration overwrite. Stable latest remains
+  behind the full candidate and installed-product acceptance gates.
+
+## [5.0.9-rc.16] - 2026-10-11
+
+- Pin Workbench 0.13.2-rc.5. Bound OpenCode's health request at both
+  response headers and JSON body so a stalled local server cannot exceed
+  the startup handshake budget before the existing CLI fallback.
+- Reproduce the old behavior using two live HTTP connections, retain the
+  failed rc.15 client acceptance and require a new official-package retest.
+- No project, knowledge, history, provider or third-party hook reset.
+  Candidate is published to next; stable latest still requires acceptance.
+
+## [5.0.9-rc.15] - 2026-10-11
+
+- Serialize registration, module removal and registry deletion for each project.
+  Recheck membership inside the wiring lease so delayed supervisor registration
+  cannot resurrect a project after keep-data unbind. Unrelated projects remain
+  independent; failed deletion can still be repaired and retried.
+- Reproduce the race with a delayed real HTTP registration and preserve the
+  downloaded rc.14 Node 22 UI failure. Include the regression in the package.
+- Use non-binding CLI readiness probes in tests; the old bind probe could take
+  the exact port while its own foreground child was starting.
+- Real MiniMax acceptance covers overlapping analyses, another commit and a
+  dirty developer draft during analysis, streaming, secondary development,
+  four installed clients and evidenced preference candidates. New downloaded
+  candidate acceptance and actual-user cutover still precede stable latest.
+
+## [5.0.9-rc.14] - 2026-10-11
+
+- Vendor engine 0.2.3-rc.7: isolated maintenance consumes frozen evidence even
+  while the user edits or commits in the source repository. Do not mistake live
+  development for analyzer writes; retain live-source protection for custom
+  analyzers without the isolation capability.
+- Add a paused child-worker regression covering another commit, uncommitted
+  drafts, frozen attribution, same-project FIFO and unchanged path/tool guards.
+- Existing-user npm acceptance verified real MiniMax streaming, retained v5
+  history/configuration, D-root indexes and index-only e9f6560 recovery. Preserve
+  the actual rc.13 PROJECT_BUSY failure and require a real mid-analysis commit
+  retest from downloaded rc.14 before stable promotion.
+
+## [5.0.9-rc.13] - 2026-10-11
+
+- Give native Agent session creation and input setup a bounded 90-second proxy
+  budget. Ordinary API reads/abort/permissions retain 10 seconds; SSE streaming
+  and folder-picker contracts are unchanged.
+- Record safe proxy failure categories and deadlines without raw errors or URL
+  queries. Preserve MODULE_UNREACHABLE compatibility and add optional details.
+- Reproduce the installed OpenCode cold-start failure with a real delayed HTTP
+  server; verify the targeted budget, unrelated routes and credential redaction.
+- Retain rc.12 real acceptance and failed OpenCode results separately; require
+  a newly downloaded candidate and cold-client retest before user upgrade.
+
+## [5.0.9-rc.12] - 2026-10-11
+
+- Vendor engine 0.2.3-rc.6 to address the Windows transient state-file rename
+  failure exposed by installed rc.11 fault acceptance. Use exclusive random
+  temporary files and bounded sharing retries, retain durable state on failure,
+  and never unlink live state to force replacement.
+- Add deterministic sharing-violation, permanent-lock, foreign-temp and
+  disk-full regressions; all 39 engine tests pass on Node 22 and Node 24.
+- Preserve the rc.11 failure and require new installed acceptance before any
+  existing-user upgrade or stable latest promotion.
+
+## [5.0.9-rc.11] - 2026-10-11
+
+- Pin vector-hub 1.0.8-rc.3 and vendor engine 0.2.3-rc.5. Raw commit
+  conversations and internal backups are analysis evidence, not knowledge.
+  Exclude them from managed indexes, search and get; retain source evidence.
+- Prune stale derived records during sync and rebuild once on source-policy
+  upgrade, without repeating paid whole-index work on ordinary restarts.
+- Keep standalone vector-hub general document support unchanged.
+- Record both original failing regressions and successful Node 22/24 reruns;
+  installed, real model and existing-v5 gates still precede latest promotion.
+
+## [5.0.9-rc.10] - 2026-10-11
+
+- Preserve acknowledged brain/domain knowledge-directory bindings when changing
+  the knowledge root. Only derived indexes and future imports/shared scopes use
+  the new root; existing knowledge and confirmed memories stay in place.
+- Persist bindings in shell metadata, reject implicit rebinding, and report
+  shared-scope connection failures in UI and safe structured logs.
+- Add real-engine regression for confirmed memory, domain retrieval, restart,
+  new domain registration, offline retry and protected bindings on Node 22/24.
+- Candidate acceptance still precedes the existing-v5 upgrade and stable latest.
+
 ## [5.0.9-rc.9] - 2026-10-11
 
 - Vendor engine 0.2.3-rc.4. Freeze existing target paths and hashes before

package/README.md

@@ -194,13 +194,18 @@ project-knowledge
 ```
 
 The user selects a global knowledge root before importing projects. That root
-only chooses the directory for future imports. Each imported project stores an
+chooses directories for future imports, new shared scopes, and derived vector
+indexes (`<knowledge root>/.indexes`). Each imported project stores an
 absolute, fixed `knowledgePath`; changing the global root does not move existing
 projects.
 
-The selected knowledge root contains only authoritative project Markdown.
-Settings, metadata, indexes, caches, runtime state, logs, and recovery assets
-remain in the internal data directory:
+Existing project and shared-knowledge directories do not move when the root
+changes. Brain/domain directory bindings are retained in the shell settings
+after the engine acknowledges them. Existing engine bindings are reused when
+first recording those fields. A failed registration is shown as pending, not
+healthy. Old index directories are retained; indexes rebuild at the new root.
+Settings, registration metadata, caches, runtime state, logs, and recovery
+assets remain in the internal data directory; vector payloads do not:
 
 ```text
 ~/.project-knowledge-v5/
@@ -220,6 +225,8 @@ remain in the internal data directory:
 └── recovery/                             # migrations, promotion/index backups
 
 <selected knowledge root>/
+├── .indexes/                            # rebuildable vector payloads
+├── _shared/<brain or domain ID>/         # fixed shared-knowledge bindings
 └── <project storage name>/
     ├── README.md                         # when produced by verified knowledge
     ├── GOAL.md

package/_modules/knowledge-engine/README.md

@@ -1,5 +1,7 @@
 # knowledge-engine
 
+正式知识检索（包括 `get`）排除 `dev-conversations`、内部会话、备份与隐藏目录。提交会话只作为分析证据，不直接充当已晋升知识；原始证据仍由事件模块保留。
+
 > 开发前读 [AGENTS.md](AGENTS.md)。该指南中的脚手架状态是历史背景；当前运行契约及实现状态以本 README 为准。
 
 `project-knowledge` 模块家族的第四块：**知识引擎**。owns 两个职责面，shell 只负责连接与投影（"The shell owns no features"）：
@@ -39,6 +41,8 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 
 本模块零新增 npm 依赖、CommonJS、Node ≥18；无头 Agent SDK 由宿主已安装的 Workbench/SDK 提供，缺失时明确失败，不退回假分析。完整产品的 Node 门槛为 ≥22。
 
+隔离无头分析只读冻结证据、只写 staging，不以开发工作树的前后变化判定失败。用户可以在分析中继续编辑或提交；当前任务仍归属冻结提交，后续提交按项目 FIFO 执行。未声明隔离冻结证据能力的自定义分析器仍保留源码变更检查；目录越界、工具权限和晋升校验不变。
+
 每次真实分析在只读证据区冻结已有知识的目标路径与哈希清单，覆盖未被检索选中的文件；重试复用该清单。Agent 不得把“未检索到”当作“文件不存在”，也不得用部分片段覆盖完整旧文档；无法保留原文时只追加当前提交的变更记录。已有目标仍由晋升校验拒绝非法 create，不自动改为覆盖。清单仅保存元数据，不把整个知识树复制到每次运行中。
 
 ## API
@@ -58,7 +62,7 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 | GET | `/api/snapshot`、`/api/progress` | 持久化快照 / 快照先行的 SSE 更新 |
 | GET / POST | `/api/events` | 真实事件查询 / 仅调试模式注入事件 |
 | POST | `/api/bridge/notify` | 唤醒 journal 消费；通知丢失仍由轮询恢复 |
-| GET / PATCH | `/api/memories`、`/api/memories/:id` | 候选和已确认记忆；编辑、确认、忽略持久化 |
+| GET / PATCH | `/api/memories`、`/api/memories/:id` | 按 status/scopeType/scopeId 筛选；一次编辑内容、适用范围和确认状态；来源证据只读 |
 | POST | `/api/scopes` | 外壳投影智脑、领域共享目录；受运行期鉴权保护 |
 | POST | `/api/runtime-config` | 运行期模型配置，仅保留在内存；受鉴权保护 |
 | GET | `/api/runtime-auth` | 本机服务确认运行期鉴权；受鉴权保护，不对浏览器反代 |
@@ -81,7 +85,11 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 - 项目、领域、智脑检索使用包含范围。未分配领域不是共享领域：领域范围只包含当前项目与智脑共享知识；显式加入同一领域后才包含其他项目。整个智脑范围仍包含全部同智脑项目。向量只提供排序，显示内容必须来自当前真实文件；索引不可用时降级为文件检索。
 - 已晋升提交的 SHA 或短 SHA 在自然语言查询中仍作为标识符匹配，只返回当前文件的晋升依据；仅在原始会话中提到相同 SHA 不构成知识晋升引用。多个提交标识符可以一起查询。
 - 候选必须有已晋升文件中的引用依据，未确认候选不能进入任务。确认记录原子持久化后写共享记忆文件，派生索引异步更新，索引失败不会撤销有效记忆。
+- 记忆的适用范围为 `global/domain/project`，目标用 `scopeId` 指定；来源项目/领域不等于适用范围。新候选默认来源项目，分析器只有明确证据时才建议领域/全局；用户审核时可以编辑内容并选择当前智脑中的其他已有目标。原始总结与证据保持不变，同一范围内容去重，忽略和编辑后的原候选不会重复生成。
+- 长期记忆统一保存在已绑定的智脑共享目录：`memories/confirmed.md`（全局）、`memories/domains/<id>.md`、`memories/projects/<id>.md`。不创建第二份项目知识目录。现有 v5 缺少范围字段的记忆仍按全局解释；不读取 pre-v5 状态、不重扫历史。
+- 任务检索只允许当前项目、当前所属领域与全局的已确认记忆，即使检索整个智脑也不放宽专属记忆范围。过滤在排名之前完成，`get` 同样校验；向量旧内容不能绕过当前状态和文件一致性校验。已确认记录修改范围会同步清理旧投影；写入失败显示待同步并自动重试，未同步文件不能进入上下文。
 - 旧格式不读取、不自动迁移。损坏的正式状态不覆盖、不清空。
+- 引擎状态复用受控原子写入：独占随机临时文件、文件同步、Windows 短暂共享冲突有界重试；永久失败保留原状态并清理本次临时文件，绝不先删正式状态。
 
 ## 验证与尚未验收项
 

package/_modules/knowledge-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/ai-coding-knowledge-engine",
-  "version": "0.2.3-rc.4",
+  "version": "0.2.4-rc.1",
   "description": "Knowledge engine module for project-knowledge: commit-boundary triggered knowledge analysis/generation (trigger plane) and retrieval for development assistants (retrieval plane).",
   "license": "Apache-2.0",
   "main": "src/server.js",

package/_modules/knowledge-engine/src/coordinator.js

@@ -39,7 +39,15 @@ class EngineCoordinator extends EventEmitter {
     this.sharedIndexJobs = new Map();
     this.sharedIndexDirty = new Set();
     this.sharedIndexQueue = Promise.resolve();
-    this.memories = new MemoryService(store, { onMaterialized: scope => { this.indexSharedScope(scope).catch(() => {}); } });
+    this.memories = new MemoryService(store, {
+      getIndexStatus: scope => scope && this.sharedIndexJobs.has(scope.id) ? 'pending' : null,
+      onMaterialized: scope => { this.indexSharedScope(scope).catch(() => {}); },
+      onSyncChange: (scope, code) => {
+        this.emit('progress', store.addEvent({ type: 'memory.sync', scopeId: scope.id, summary: code ? `记忆文件待恢复（${code}）` : '记忆文件已恢复同步' }));
+        const log = code ? 'error' : 'info';
+        Promise.resolve(this.diagnostics[log]('knowledge.memory.' + (code ? 'write_failed' : 'write_recovered'), code ? '记忆状态已保存，文件待恢复。' : '记忆文件已恢复同步。', { phase: 'memory-sync', context: { scopeId: scope.id, code: code || null } })).catch(() => {});
+      },
+    });
     this.projectStore = {
       readConfig: id => { const p = store.getProject(id); if (!p) throw Object.assign(new Error('项目未登记。'), { code: 'PROJECT_NOT_FOUND' }); return { ...p, displayName: p.name, automation: { enabled: true } }; },
       readState: id => store.readRuntime(id),
@@ -50,7 +58,7 @@ class EngineCoordinator extends EventEmitter {
     this.retrieval = new EngineRetrieval({ layout: this.layout, projectStore: this.projectStore, registryStore, store, memories: this.memories, vectorUrl: this.vectorUrl });
     this.conversations = new ConversationStore({ layout: this.layout, projectStore: this.projectStore });
     this.analyzer = options.analyzer || new HeadlessAnalyzer({ resolveProfile: id => this.profiles.get(id) || this.profiles.get('default'), timeoutMs: options.timeoutMs });
-    this.promotion = new KnowledgePromotionService({ layout: this.layout, logger: this.diagnostics, projectStore: this.projectStore, analyzer: { runClaim: async input => {
+    this.promotion = new KnowledgePromotionService({ layout: this.layout, logger: this.diagnostics, projectStore: this.projectStore, analyzer: { sourceReadMode: this.analyzer.sourceReadMode, runClaim: async input => {
       const run = this.currentRun(input.projectId);
       store.updateRun(run.runId, { analysisRunId: input.claim.runId, phase: 'analyzing' });
       this.notify(run, '正在分析冻结的提交证据');
@@ -291,6 +299,7 @@ class EngineCoordinator extends EventEmitter {
     return run;
   }
   async close() {
+    await this.memories.close();
     this.closed = true; clearInterval(this.poll);
     this.bridge.close?.();
     await this.analyzer.close?.();

package/_modules/knowledge-engine/src/headless-analyzer.js

@@ -6,6 +6,7 @@ const { finalizeAnalysisOutput } = require('./analysis-output');
 const { freezeKnowledgeTargets } = require('./knowledge-targets');
 
 class HeadlessAnalyzer {
+  get sourceReadMode() { return 'isolated-frozen-evidence'; }
   constructor({ resolveProfile, timeoutMs = 15 * 60 * 1000, workerPath = path.join(__dirname, 'analysis-worker.js') } = {}) { this.resolveProfile = resolveProfile; this.timeoutMs = timeoutMs; this.workerPath = workerPath; this.children = new Map(); this.closed = false; }
   async runClaim(input) {
     if (this.closed) throw Object.assign(new Error('分析服务正在关闭。'), { code: 'WORKER_STOPPED', retryable: true });
@@ -50,7 +51,7 @@ class HeadlessAnalyzer {
         if (!requested) outcome = Object.assign(new Error('后台分析进程意外退出。'), { code: 'WORKER_EXITED', retryable: true });
         if (outcome) reject(outcome); else resolve();
       });
-      const memoryContract = '\nYou may optionally include memoryCandidates in manifest.json: [{text, entryId, quote}]. Only suggest durable user preferences explicitly evidenced in a promoted document; quote must be an exact excerpt (at least 8 characters) from that document. Never infer preferences from code style alone. These stay unconfirmed until the user accepts them.';
+      const memoryContract = '\nYou may optionally include memoryCandidates in manifest.json: [{text, entryId, quote, scopeType}]. Only suggest durable user preferences explicitly evidenced in a promoted document; quote must be an exact excerpt (at least 8 characters) from that document. Never infer preferences from code style alone. scopeType is project (default), domain or global. Recommend domain/global only when the quoted owner requirement explicitly applies across that domain/all projects; ambiguous or local requirements stay project-scoped. Do not invent target IDs. These stay unconfirmed until the user edits their text/scope and accepts them.';
       const languageContract = input.config?.knowledgeLanguage === 'en-US' ? '\nOUTPUT LANGUAGE: English. Preserve identifiers and verbatim evidence quotations.' : '\n输出语言：简体中文。知识正文、operations[].reason 与候选记忆用简体中文；代码标识、路径、哈希和原文证据引用保持不变。';
       child.send({ profile, projectId: input.projectId, runId: input.claim.runId, commitSha: input.claim.commitSha, prompt: `${frameFrozenEvidence(input.prompt)}${contract}${pathContract}${targetContract}${memoryContract}${languageContract}`, manifestPath: input.manifestPath, stagingPath: input.stagingPath, safetyPolicy: input.safetyPolicy }, error => { if (error) stop(Object.assign(new Error('无法发送分析任务。'), { code: 'WORKER_START_FAILED', retryable: true })); });
     });

package/_modules/knowledge-engine/src/memories.js

@@ -6,8 +6,69 @@ const AtomicFile = require('./runtime/atomic-file');
 const { RuntimeLayout } = require('./runtime/layout');
 const { validateProjectId, DomainError } = require('./runtime/contracts');
 
+const TYPES = ['global', 'domain', 'project'];
+const normalized = text => String(text).toLowerCase().replace(/\s+/g, ' ').trim();
+const fingerprint = (brainId, type, id, text) => crypto.createHash('sha256').update(`${brainId}:${type}:${id}:${normalized(text)}`).digest('hex');
+
 class MemoryService {
-  constructor(store, options = {}) { this.store = store; this.layout = new RuntimeLayout(store.dataDir); this.onMaterialized = options.onMaterialized; }
+  constructor(store, options = {}) {
+    this.store = store; this.layout = new RuntimeLayout(store.dataDir); this.onMaterialized = options.onMaterialized;
+    this.syncErrors = new Map(); this.closed = false; this.onSyncChange = options.onSyncChange; this.writes = new Set();
+    this.getIndexStatus = options.getIndexStatus;
+  }
+  lock() { return this.layout.getRuntimePath('locks', 'memories.lock'); }
+  scopeOf(memory) { return { type: memory.scopeType || 'global', id: memory.scopeId || memory.brainId || 'brain-default' }; }
+  brainScope(brainId) { return this.store.state.sharedScopes.find(s => s.kind === 'brain' && s.brainId === brainId); }
+  target(memory) {
+    const scope = this.scopeOf(memory), brainId = memory.brainId || 'brain-default';
+    const target = scope.type === 'global' ? this.brainScope(brainId) : scope.type === 'domain'
+      ? this.store.state.sharedScopes.find(s => s.kind === 'domain' && s.id === scope.id && s.brainId === brainId)
+      : this.store.listProjects().find(p => p.projectId === scope.id && p.brainId === brainId && p.enabled !== false);
+    return { name: target?.name || scope.id, available: Boolean(target) };
+  }
+  validateScope(type, id, brainId) {
+    if (!TYPES.includes(type)) throw new DomainError('INVALID_ARGUMENT', '适用范围无效。');
+    validateProjectId(id);
+    if (type === 'global' && id !== brainId || type !== 'global' && !this.target({ brainId, scopeType: type, scopeId: id }).available) throw new DomainError('INVALID_ARGUMENT', '所选记忆目标不存在或不属于当前智脑。');
+  }
+  entry(memory) {
+    const scope = this.scopeOf(memory);
+    if (scope.type === 'global') return 'memories/confirmed.md';
+    validateProjectId(scope.id);
+    return `memories/${scope.type === 'domain' ? 'domains' : 'projects'}/${scope.id}.md`;
+  }
+  descriptor(entry) {
+    if (entry === 'memories/confirmed.md') return { type: 'global' };
+    const match = /^memories\/(domains|projects)\/([A-Za-z0-9][A-Za-z0-9._-]*)\.md$/.exec(entry);
+    if (!match) return null;
+    try { validateProjectId(match[2]); } catch { return null; }
+    return { type: match[1] === 'domains' ? 'domain' : 'project', id: match[2] };
+  }
+  file(scope, entry = 'memories/confirmed.md') { return path.join(scope.knowledgePath, ...entry.split('/')); }
+  safeFile(scope, entry) {
+    const file = this.file(scope, entry);
+    if (!this.descriptor(entry) || !this.layout.isPathInside(scope.knowledgePath, file, { realpath: true }) || fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new DomainError('PATH_OUTSIDE_ROOT', '记忆文件目录越界。', { status: 403 });
+    return file;
+  }
+  confirmed(brainId, entry) { return this.store.state.memories.filter(m => m.status === 'confirmed' && (m.brainId || 'brain-default') === brainId && this.entry(m) === entry); }
+  applicable(memory, project) {
+    if (!project || memory.status !== 'confirmed' || (memory.brainId || 'brain-default') !== project.brainId || !this.target(memory).available) return false;
+    const scope = this.scopeOf(memory);
+    return scope.type === 'global' || scope.type === 'domain' && scope.id === project.domainId || scope.type === 'project' && scope.id === project.projectId;
+  }
+  readableEntry(scope, entry, project) {
+    return scope.kind === 'brain' && !this.syncErrors.has(scope.id) && this.validFile(scope, entry) && this.confirmed(scope.brainId, entry).some(m => this.applicable(m, project));
+  }
+  memoryForChunk(scope, entry, heading) {
+    return this.confirmed(scope.brainId, entry).find(m => (Array.isArray(heading) ? heading : String(heading).split(' > ')).includes(m.id));
+  }
+  project(memory) {
+    const scope = this.scopeOf(memory), target = this.target(memory), brain = this.brainScope(memory.brainId || 'brain-default');
+    return { ...memory, scopeType: scope.type, scopeId: scope.id, targetName: target.name, targetAvailable: target.available,
+      syncStatus: memory.status !== 'confirmed' ? 'not-required' : brain && !this.syncErrors.has(brain.id) && this.validFile(brain, this.entry(memory)) ? 'ready' : 'pending',
+      indexStatus: memory.status === 'confirmed' ? this.getIndexStatus?.(brain) || (brain?.index?.error ? 'failed' : brain?.index?.status || 'pending') : 'not-required',
+      ...(brain && this.syncErrors.has(brain.id) ? { syncError: this.syncErrors.get(brain.id) } : {}) };
+  }
   async configure(scopes) {
     if (!Array.isArray(scopes)) throw new DomainError('INVALID_ARGUMENT', '共享范围必须是数组。');
     const ids = new Set();
@@ -31,7 +92,10 @@ class MemoryService {
     await this.recover();
     return projected;
   }
-  list({ brainId, status } = {}) { return this.store.state.memories.filter(m => (!brainId || m.brainId === brainId) && (!status || m.status === status)); }
+  list({ brainId, status, scopeType, scopeId } = {}) {
+    if (scopeType && !TYPES.includes(scopeType)) throw new DomainError('INVALID_ARGUMENT', '记忆筛选范围无效。');
+    return this.store.state.memories.filter(m => (!brainId || m.brainId === brainId) && (!status || m.status === status) && (!scopeType || this.scopeOf(m).type === scopeType) && (!scopeId || this.scopeOf(m).id === scopeId)).map(m => this.project(m));
+  }
   capture(run) {
     const project = this.store.getProject(run.projectId);
     if (!project || !run.promotedAt) return;
@@ -43,43 +107,88 @@ class MemoryService {
       const entryId = String(raw.entryId || '');
       const file = path.resolve(project.knowledgePath, entryId);
       if (!text || text.length > 2000 || quote.length < 8 || !run.staging.operations?.some(op => op.operation !== 'delete' && op.path === entryId) || !this.layout.isPathInside(project.knowledgePath, file, { realpath: true }) || !fs.existsSync(file) || !fs.readFileSync(file, 'utf8').includes(quote)) continue;
-      const fingerprint = crypto.createHash('sha256').update(`${project.brainId || 'brain-default'}:${text.toLowerCase().replace(/\s+/g, ' ')}`).digest('hex');
-      if (this.store.state.memories.some(m => m.fingerprint === fingerprint)) continue;
-      this.store.state.memories.push({ id: `memory-${crypto.randomUUID()}`, fingerprint, brainId: project.brainId || 'brain-default', domainId: project.domainId || null, text, status: 'candidate', evidence: { projectId: project.projectId, commitSha: run.commitSha, runId: run.runId, entryId, quote }, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
+      const brainId = project.brainId || 'brain-default';
+      const scopeType = raw.scopeType === 'global' ? 'global' : raw.scopeType === 'domain' && project.domainId ? 'domain' : 'project';
+      const scopeId = scopeType === 'global' ? brainId : scopeType === 'domain' ? project.domainId : project.projectId;
+      const key = fingerprint(brainId, scopeType, scopeId, text);
+      if (this.store.state.memories.some(m => m.captureFingerprint === key || fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key || !m.scopeType && m.evidence.projectId === project.projectId && normalized(m.originalText || m.text) === normalized(text))) continue;
+      this.store.state.memories.push({ id: `memory-${crypto.randomUUID()}`, fingerprint: key, captureFingerprint: key, brainId, domainId: project.domainId || null, scopeType, scopeId, text, originalText: text, status: 'candidate', evidence: { projectId: project.projectId, commitSha: run.commitSha, runId: run.runId, entryId, quote }, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
     }
     this.store.save();
   }
   async update(id, input) {
-    return AtomicFile.withFileLock(this.layout.getRuntimePath('locks', 'memories.lock'), async () => {
+    if (this.closed) throw new DomainError('PROJECT_BUSY', '引擎正在关闭，请稍后重试。', { status: 409 });
+    if (Object.keys(input).some(key => !['text', 'status', 'scopeType', 'scopeId'].includes(key))) throw new DomainError('INVALID_ARGUMENT', '来源证据和文件路径不能修改。');
+    const job = AtomicFile.withFileLock(this.lock(), async () => {
       const memory = this.store.state.memories.find(m => m.id === id);
       if (!memory) throw new DomainError('PROJECT_NOT_FOUND', '记忆不存在。', { status: 404 });
       if (input.text !== undefined && (typeof input.text !== 'string' || !input.text.trim() || input.text.length > 2000)) throw new DomainError('INVALID_ARGUMENT', '记忆内容必须为 1–2000 个字符。');
       if (input.status !== undefined && !['confirmed', 'ignored'].includes(input.status)) throw new DomainError('INVALID_ARGUMENT', '记忆状态无效。');
       if (memory.status === 'ignored') throw new DomainError('INVALID_ARGUMENT', '该候选已忽略。', { status: 409 });
-      if (input.status === 'confirmed' && !this.store.state.sharedScopes.some(s => s.kind === 'brain' && s.brainId === memory.brainId)) throw new DomainError('INVALID_ARGUMENT', '请先绑定智脑共享目录。', { status: 409 });
-      Object.assign(memory, { text: input.text?.trim() || memory.text, status: input.status || memory.status, updatedAt: new Date().toISOString() });
-      // Persist confirmation before writing. Retrieval verifies the materialized
-      // file against this state, so a crash cannot inject unconfirmed content.
-      this.store.save();
-      await this.recover();
-      return memory;
+      const brainId = memory.brainId || 'brain-default', old = this.scopeOf(memory);
+      const type = input.scopeType === undefined ? old.type : input.scopeType;
+      const targetId = input.scopeId === undefined ? (type === 'global' ? brainId : type === old.type ? old.id : '') : input.scopeId;
+      if (input.status !== 'ignored' || input.scopeType !== undefined || input.scopeId !== undefined) this.validateScope(type, targetId, brainId);
+      if ((input.status || memory.status) === 'confirmed' && !this.brainScope(brainId)) throw new DomainError('INVALID_ARGUMENT', '请先绑定智脑共享目录。', { status: 409 });
+      const text = input.text?.trim() || memory.text, key = fingerprint(brainId, type, targetId, text);
+      if (this.store.state.memories.some(m => m.id !== id && fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key)) throw new DomainError('MEMORY_DUPLICATE', '该范围内已存在相同记忆。', { status: 409 });
+      const next = { ...memory, originalText: memory.originalText || memory.text, captureFingerprint: memory.captureFingerprint || fingerprint(brainId, old.type, old.id, memory.originalText || memory.text), fingerprint: key, scopeType: type, scopeId: targetId, text, status: input.status || memory.status, updatedAt: new Date().toISOString() };
+      const before = this.store.state.memories;
+      this.store.state.memories = before.map(m => m.id === id ? next : m);
+      try { this.store.save(); } catch (error) { this.store.state.memories = before; throw error; }
+      await this.materialize(); return this.project(next);
     });
+    this.writes.add(job);
+    try { return await job; } finally { this.writes.delete(job); }
   }
-  content(brainId) {
-    return '# 已确认的长期记忆\n\n' + this.list({ brainId, status: 'confirmed' }).map(m => `## ${m.id}\n\n${m.text}\n\n来源：${m.evidence.projectId} · ${m.evidence.commitSha} · ${m.evidence.entryId}\n`).join('\n');
+  content(brainId, entry = 'memories/confirmed.md') {
+    return '# 已确认的长期记忆\n\n' + this.confirmed(brainId, entry).map(m => {
+      const scope = this.scopeOf(m);
+      // Preserve legacy global bytes until the user actually edits that record.
+      const scopeText = m.scopeType ? `适用范围：${{ global: '全局', domain: '领域', project: '项目' }[scope.type]} · ${scope.id}\n\n` : '';
+      const text = m.scopeType ? m.text.replace(/^\s*(#{1,6})\s/gm, '\\$1 ') : m.text;
+      return `## ${m.id}\n\n${scopeText}${text}\n\n来源：${m.evidence.projectId} · ${m.evidence.commitSha} · ${m.evidence.entryId}\n`;
+    }).join('\n');
   }
-  file(scope) { return path.join(scope.knowledgePath, 'memories', 'confirmed.md'); }
-  async recover() {
+  existingEntries(scope) {
+    const entries = new Set(['memories/confirmed.md']);
+    for (const group of ['domains', 'projects']) {
+      const directory = path.join(scope.knowledgePath, 'memories', group);
+      if (!fs.existsSync(directory)) continue;
+      if (fs.lstatSync(directory).isSymbolicLink() || !this.layout.isPathInside(scope.knowledgePath, directory, { realpath: true })) throw new DomainError('PATH_OUTSIDE_ROOT', '记忆目录越界。', { status: 403 });
+      for (const name of fs.readdirSync(directory)) if (this.descriptor(`memories/${group}/${name}`)) entries.add(`memories/${group}/${name}`);
+    }
+    for (const memory of this.store.state.memories.filter(m => m.status === 'confirmed' && (m.brainId || 'brain-default') === scope.brainId)) entries.add(this.entry(memory));
+    return entries;
+  }
+  async materialize() {
+    clearTimeout(this.retryTimer);
     for (const scope of this.store.state.sharedScopes.filter(s => s.kind === 'brain')) {
-      const file = this.file(scope);
-      if (!this.layout.isPathInside(scope.knowledgePath, file, { realpath: true }) || fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new DomainError('PATH_OUTSIDE_ROOT', '记忆文件目录越界。', { status: 403 });
-      const content = this.content(scope.brainId);
-      if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== content) {
-        AtomicFile.writeFileAtomic(file, content);
-        await this.onMaterialized?.(scope);
+      try {
+        let changed = false;
+        for (const entry of this.existingEntries(scope)) {
+          const file = this.safeFile(scope, entry), content = this.content(scope.brainId, entry);
+          if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== content) { AtomicFile.writeFileAtomic(file, content); changed = true; }
+        }
+        const recovered = this.syncErrors.delete(scope.id);
+        if (recovered) this.onSyncChange?.(scope, null);
+        if (changed) await this.onMaterialized?.(scope);
+      } catch (error) {
+        const code = error.code || 'MEMORY_WRITE_FAILED', prior = this.syncErrors.get(scope.id);
+        this.syncErrors.set(scope.id, code);
+        if (prior !== code) this.onSyncChange?.(scope, code);
       }
     }
+    if (this.syncErrors.size && !this.closed) { this.retryTimer = setTimeout(() => this.recover().catch(() => {}), 5000); this.retryTimer.unref(); }
+  }
+  async recover() {
+    if (this.recovery) return this.recovery;
+    this.recovery = AtomicFile.withFileLock(this.lock(), () => this.materialize()).finally(() => { this.recovery = null; });
+    return this.recovery;
+  }
+  validFile(scope, entry = 'memories/confirmed.md') {
+    try { const file = this.safeFile(scope, entry); return fs.existsSync(file) && fs.readFileSync(file, 'utf8') === this.content(scope.brainId, entry); } catch { return false; }
   }
-  validFile(scope) { const file = this.file(scope); return fs.existsSync(file) && fs.readFileSync(file, 'utf8') === this.content(scope.brainId); }
+  async close() { this.closed = true; clearTimeout(this.retryTimer); await Promise.allSettled([...this.writes, this.recovery].filter(Boolean)); }
 }
 module.exports = { MemoryService };

package/_modules/knowledge-engine/src/retrieval.js

@@ -2,7 +2,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { KnowledgeRetrievalService } = require('./runtime/knowledge-retrieval-service');
-const { listMarkdownFiles } = require('./runtime/markdown-knowledge-indexer');
+const { listMarkdownFiles, isExcludedKnowledgePath } = require('./runtime/markdown-knowledge-indexer');
 const { DomainError } = require('./runtime/contracts');
 
 class EngineRetrieval extends KnowledgeRetrievalService {
@@ -45,15 +45,22 @@ class EngineRetrieval extends KnowledgeRetrievalService {
     return this.store.state.sharedScopes.filter(s => s.brainId === registration.brainId && (s.kind === 'brain' || range === 'brain' || registration.domainId && s.domainId === registration.domainId)).map(s => ({ projectId: s.id, spaceId: `${s.kind}:${s.id}`, knowledgePath: s.knowledgePath, weight: s.kind === 'brain' ? 0.6 : 0.75, reason: s.kind }));
   }
   scanCurrent(scopes) {
+    const registration = this.store.getProject(scopes.find(s => s.reason === 'primary')?.projectId);
     const ordinary = scopes.filter(s => this.store.getProject(s.projectId));
     const shared = scopes.filter(s => !this.store.getProject(s.projectId));
     const result = super.scanCurrent(ordinary);
+    for (const [id, candidate] of result.candidates) if (candidate.entryId.startsWith('memories/')) result.candidates.delete(id);
     if (!shared.length) return result;
     const scanner = new KnowledgeRetrievalService({ layout: this.layout, projectStore: { readState: () => ({ index: {} }) } });
     const extra = scanner.scanCurrent(shared);
     for (const [id, candidate] of extra.candidates) {
       const scope = this.store.state.sharedScopes.find(s => s.id === candidate.projectId);
-      if (candidate.entryId.startsWith('memories/') && (scope.kind !== 'brain' || candidate.entryId !== 'memories/confirmed.md' || !this.memories?.validFile(scope))) continue;
+      if (candidate.entryId.startsWith('memories/')) {
+        if (!this.memories?.readableEntry(scope, candidate.entryId, registration) || !this.memories.memoryForChunk(scope, candidate.entryId, candidate.headingPath)) continue;
+        const memory = this.memories.memoryForChunk(scope, candidate.entryId, candidate.headingPath), type = this.memories.scopeOf(memory).type;
+        candidate.scopeWeight = { project: 1, domain: 0.75, global: 0.6 }[type];
+        candidate.title = `${{ project: '项目记忆', domain: '领域记忆', global: '全局记忆' }[type]} · ${this.memories.target(memory).name}`;
+      } else if (scopes.find(s => s.projectId === candidate.projectId)?.memoryOnly) continue;
       result.candidates.set(id, candidate);
     }
     result.scopeHealth.push(...extra.scopeHealth);
@@ -97,12 +104,19 @@ class EngineRetrieval extends KnowledgeRetrievalService {
         && (input.scope === 'brain' || p.projectId === registration.projectId || registration.domainId && p.domainId === registration.domainId)).map(p => ({ projectId: p.projectId, spaceId: `project:${p.projectId}`, knowledgePath: p.knowledgePath, weight: p.projectId === registration.projectId ? 1 : 0.88, reason: p.projectId === registration.projectId ? 'primary' : input.scope }));
       scopes.push(...this.sharedScopes(registration, input.scope));
     }
+    if (!scopes.some(s => s.spaceId === `brain:${registration.brainId}`)) {
+      scopes.push(...this.sharedScopes(registration, 'domain').filter(s => s.reason === 'brain').map(s => ({ ...s, memoryOnly: true })));
+    }
     const result = await super.search({ ...input, project, scopes });
     result.results = result.results.map(row => {
       const run = this.store.listRuns(row.scope_project_id).find(r => r.promotedAt && r.staging?.operations?.some(op => op.path === row.entry_id));
       const source = this.store.getProject(row.scope_project_id) || this.store.state.sharedScopes.find(s => s.id === row.scope_project_id);
-      return { ...row, projectName: source?.name || row.scope_project_id, path: row.entry_id, snippet: row.chunk_text, score: row.relevance_score, projectId: row.scope_project_id, commitSha: run?.commitSha || null };
+      const memory = source?.kind === 'brain' && row.entry_id.startsWith('memories/') ? this.memories.memoryForChunk(source, row.entry_id, row.heading_path) : null;
+      return { ...row, projectName: source?.name || row.scope_project_id, path: row.entry_id, snippet: row.chunk_text, score: row.relevance_score, projectId: row.scope_project_id, commitSha: memory?.evidence.commitSha || run?.commitSha || null, ...(memory ? { memoryScopeType: this.memories.scopeOf(memory).type, memoryScopeId: this.memories.scopeOf(memory).id, memoryId: memory.id } : {}) };
     });
+    const slots = result.results.map((r, i) => r.memoryId ? i : -1).filter(i => i >= 0);
+    const ordered = slots.map(i => result.results[i]).sort((a, b) => ({ project: 0, domain: 1, global: 2 }[a.memoryScopeType] - { project: 0, domain: 1, global: 2 }[b.memoryScopeType]) || b.score - a.score);
+    slots.forEach((slot, i) => { result.results[slot] = ordered[i]; });
     return result;
   }
   async ask(input) {
@@ -116,10 +130,11 @@ class EngineRetrieval extends KnowledgeRetrievalService {
     if (input.spaceId && !scope && input.spaceId !== `project:${registration.projectId}`) throw new DomainError('PROJECT_NOT_FOUND', '知识范围与项目归属不匹配。', { status: 404 });
     const project = scope ? { projectId: scope.id, knowledgePath: scope.knowledgePath } : registration;
     const entryId = String(input.entryId || input.entry || '').replace(/\\/g, '/');
+    if (isExcludedKnowledgePath(entryId)) throw new DomainError('PATH_OUTSIDE_ROOT', '会话证据与内部数据不能作为正式知识读取。', { status: 403 });
     const target = path.resolve(project.knowledgePath, entryId);
     if (!entryId || !/\.md$/i.test(target) || !this.layout.isPathInside(project.knowledgePath, target, { realpath: true })) throw new DomainError('PATH_OUTSIDE_ROOT', '知识文件越界。', { status: 403 });
     if (!fs.existsSync(target) || !fs.statSync(target).isFile() || fs.lstatSync(target).isSymbolicLink()) throw new DomainError('PROJECT_NOT_FOUND', '知识文件不存在。', { status: 404 });
-    if (scope && entryId.startsWith('memories/') && (entryId !== 'memories/confirmed.md' || !this.memories?.validFile(scope))) throw new DomainError('PROJECT_NOT_FOUND', '记忆尚未完成确认写入。', { status: 404 });
+    if (entryId.startsWith('memories/') && (!scope || !this.memories?.readableEntry(scope, entryId, registration))) throw new DomainError('PROJECT_NOT_FOUND', '记忆尚未同步或不适用于当前项目。', { status: 404 });
     return { ok: true, projectId: project.projectId, projectSlug: project.projectId, entryId, source: 'markdown', chunks: [{ chunk_text: fs.readFileSync(target, 'utf8'), entry_id: entryId, space_id: scope ? `${scope.kind}:${scope.id}` : `project:${project.projectId}` }] };
   }
   async history(input) {

package/_modules/knowledge-engine/src/runtime/contracts.js

@@ -48,6 +48,7 @@ const ANALYSIS_PHASES = Object.freeze([
 
 const ERROR_CODES = Object.freeze([
   'INVALID_ARGUMENT',
+  'MEMORY_DUPLICATE',
   'INVALID_TRIGGER',
   'SCHEMA_UNSUPPORTED',
   'DATA_CORRUPT',

package/_modules/knowledge-engine/src/runtime/knowledge-promotion.js

@@ -312,7 +312,11 @@ class KnowledgePromotionService {
     if (!claim || claim.projectId !== projectId || !claim.runId || !claim.commitSha) throw new DomainError('INVALID_ARGUMENT', 'Active claim is required for knowledge promotion.');
     const operationId = input.operationId || claim.operationId || createId('op');
     const stagingPath = this.prepareStaging(projectId, claim.runId);
-    const beforeSource = await gitStatus(config.repoPath);
+    // The isolated worker cannot read or write the live repository. A user may
+    // keep developing while it consumes frozen evidence; live status is neither
+    // its input nor proof of worker writes. Keep the guard for other analyzers.
+    const verifyLiveSource = this.analyzer?.sourceReadMode !== 'isolated-frozen-evidence';
+    const beforeSource = verifyLiveSource ? await gitStatus(config.repoPath) : null;
     try {
       if (!this.analyzer || typeof this.analyzer.runClaim !== 'function') throw new DomainError('INVALID_ARGUMENT', 'Knowledge analyzer is unavailable.', { status: 503, retryable: true });
       const analyzerResult = await this.analyzer.runClaim({
@@ -329,7 +333,7 @@ class KnowledgePromotionService {
         }),
       });
       if (analyzerResult && analyzerResult.ok === false) throw new DomainError('INVALID_ARGUMENT', analyzerResult.error || 'Knowledge analyzer failed.', { status: 500, retryable: true });
-      const afterSource = await gitStatus(config.repoPath);
+      const afterSource = verifyLiveSource ? await gitStatus(config.repoPath) : null;
       if (beforeSource != null && afterSource != null && beforeSource !== afterSource) {
         throw new DomainError('PROJECT_BUSY', 'Source repository changed during knowledge analysis.', { status: 409, retryable: true });
       }