docs: finalize integrated local product state

This commit is contained in:
inman
2026-09-01 11:59:13 +08:00
parent e32041f31e
commit fac08e975d
4 changed files with 56 additions and 24 deletions

View File

@@ -8,7 +8,7 @@
| `electron/coding-plugins/account-plugin-cache.ts`, `marketplace-client.ts`, and `package-store.ts` | Main-owned Account Library cache, authenticated server client, and atomic immutable device installation store | Account acquisition and device installation are separate. Package bytes switch atomically only after descriptor, signature, archive, client-range, and provenance checks; failed updates preserve the prior current release. |
| `electron/coding-plugins/effective-resolver.ts`, `registry.ts`, `project-service.ts`, and `electron/coding-runtime/pi/**` | One effective installed-plugin projection and frozen parent logical-thread runtime snapshot | Project enablement and Agent Skill assignment are preserved independently. Only trusted, compatible, installed, policy-admitted resources enter a new parent logical thread; child workers remain empty and active threads retain frozen bytes until disposal. |
| `electron/coding-plugins/adapters/game-resource.ts` and `electron/services/game-resource-client.ts` | Provider-neutral `makelore.game-resource` hosted tool adapter and Main-owned Works Square transport | Tools materialize only from an eligible frozen `platform_hosted` parent snapshot. Metered mutations require explicit confirmation and stable logical operation identity; Renderer/Pi never receive Provider URLs, credentials, balances, raw responses, or Provider job IDs. |
| `electron/api/routes/plugin-marketplace.ts`, `src/stores/plugin-marketplace.ts`, `src/pages/PluginMarketplace/`, `src/pages/MyPlugins/`, and `src/pages/ProjectPlugins/` | Bounded Main routes and Renderer projections for catalog, Library, device, and project actions | Renderer receives no Account token, filesystem path, Admission, package bytes, or signed download URL. Catalog/Library/device/project generations prevent stale A/B or cross-action results from replacing current state. |
| `electron/api/routes/plugin-marketplace.ts`, `src/stores/plugin-marketplace.ts`, `src/components/plugins/PluginServices.tsx`, `src/lib/plugin-services.ts`, `src/pages/ProjectConfiguration/`, `src/pages/PluginMarketplace/`, `src/pages/MyPlugins/`, and `src/pages/ProjectPlugins/` | Bounded Main routes and one Project Configuration Plugin Services surface for catalog, Library, device, and project actions | Renderer receives no Account token, filesystem path, Admission, package bytes, or signed download URL. Discover/mine/project are URL-backed sheet tabs; former standalone routes only redirect to those tabs. Catalog/Library/device/project generations prevent stale A/B or cross-action results from replacing current state. |
| `src/components/works/ProjectPublishAction.tsx` | 可发布项目的一键提交、云构建轮询与用户可理解状态 | 只通过 Renderer API 提交非敏感元数据;绑定告警不终止轮询 |
| `src/lib/works-square.ts` | Renderer 侧 Works Square Host API 契约与安全错误映射 | 不接触 Token、ZIP、本地绝对路径或自动部署状态 |
| `electron/api/routes/works.ts` | Works Host API、Renderer capability 门禁、上游安全投影 | 发布凭据、打包、上传与本地绑定均在 Main 内完成 |
@@ -20,14 +20,14 @@
| `electron/services/project-packager.ts` | 受控项目扫描、静态 ZIP 生成和敏感/历史控制文件排除 | 只允许可发布 `ProjectType`,不提供 Compose 或手工 ZIP 路径 |
| `electron/services/works-submission-binding.ts` | submission binding v2 持久化与旧 schema 迁移 | 旧中间态终止为 `legacy_retired`;文件名暂作安装兼容 |
| `electron/api/works-play-url.ts` | 公共播放 URL 的共享安全校验 | 公共 `play_url` 必须同源 HTTPS 且精确匹配 App 路径 |
| `src/pages/Chat/CodingChatPanel.tsx` / `CodingConversationTimeline.tsx` / `CodingComposer.tsx` | Agent/Conversation 选择、Snapshot-first 时间线、prompt/steer/follow-up、交互、压缩、分支与附件 UI | Composer 不等待 worker 准备;所有异步结果按 project/Agent/Conversation 所有权隔离Renderer 不导入 Pi wire 类型 |
| `src/pages/Chat/CodingChatPanel.tsx` / `CodingConversationTimeline.tsx` / `CodingComposer.tsx` | Agent/Conversation 选择、Snapshot-first 时间线、prompt/steer/follow-up、交互、压缩、分支与附件 UI | Composer 不等待 worker 准备;时间线初始渲染最近 120 个节点并按 100 个节点向前扩展、保持滚动锚点;折叠过程预览固定首个可见块/首个非空行;所有异步结果按 project/Agent/Conversation 所有权隔离Renderer 不导入 Pi wire 类型 |
| `src/stores/coding-conversations.ts` / `coding-workspace.ts` | per-Conversation Snapshot/Patch、乐观提交、gap recovery 与项目级元数据 | generation/seq 严格递增;只恢复目标 ConversationSSE 重连不重放 mutation |
| `shared/coding-conversation-*.ts` / `coding-project-contracts.ts` | Main/Renderer 共用的产品中立 Conversation、project tool、subagent 与 reducer 合同 | 这是唯一公共实现Pi 事件、RPC 与 Provider 形状保持 Main-private |
| `electron/api/coding-composition.ts` / `electron/api/routes/coding-*.ts` | 唯一 Main-owned Coding composition 与 `/api/coding/*` Host API | 管理 project/Agent/Conversation、SSE、附件、文件、命令、交互和安全诊断mutation 返回 202 acceptance 且按 request id 去重 |
| `electron/coding-projects/` | `.makelore/project.json``.makelore/conversations.json` schema-v2 项目/Agent/Conversation 数据、原子持久化与项目文件能力 | 不读取或迁移 `.niancode` / `.opencode` 项目元数据legacy 内容保持 inert 且不删除 |
| `electron/coding-runtime/conversation-service.ts` | 产品级 Conversation orchestration、模型/思考强度、fork/archive/recover 与运行时门禁 | unresolved Conversation 先验证并持久化模型再首次 prepare已解析 Conversation 的模型切换复用 target runtime seam |
| `electron/coding-runtime/pi/{agent-server-process,worker-pool,worker-process,rpc-client,session-registry,event-projector}.ts` / `resources/pi-agent-server.mjs` | 一个长驻父 Agent Server 内的 per-Conversation 逻辑 Runtime/Session/channel、严格 LF JSONL RPC、generation recovery 与 Snapshot/Patch 投影 | top-level logical-turn cap 4、warm idle LRU 8线程级替换只使目标 generation 失效Server 退出使所有旧 channel 失效并在下次恢复时只重启一个 Server |
| `electron/coding-runtime/pi/{provider-config,provider-refresh,resource-loader}.ts` / `electron/api/routes/ai-proxy.ts` | Main-owned Provider catalog、secret/env 投影、资源 revision、一次凭据刷新与上游错误分类 | secret 不进入 argv/catalog/Renderer确定性的 Works user-context 缺失使缓存凭据过期并 fail fast不自动重放 mutation |
| `electron/coding-runtime/pi/{agent-server-process,worker-pool,worker-process,rpc-client,session-registry,event-projector,session-projector}.ts` / `resources/pi-agent-server.mjs` | 一个长驻父 Agent Server 内的 per-Conversation 逻辑 Runtime/Session/channel、严格 LF JSONL RPC、generation recovery 与 Snapshot/Patch 投影 | top-level logical-turn cap 4、warm idle LRU 8Session hydration 保留完整 active-branch 可见历史并把 compaction summary 留在 Main-private 模型上下文;线程级替换只使目标 generation 失效Server 退出使所有旧 channel 失效并在下次恢复时只重启一个 Server |
| `electron/coding-runtime/pi/{provider-config,provider-refresh,provider-failure,resource-loader}.ts` / `electron/api/routes/ai-proxy.ts` | Main-owned Provider catalog、secret/env 投影、资源 revision、一次凭据刷新与上游错误分类 | secret 不进入 argv/catalog/Renderer确定性的 Works user-context 缺失使缓存凭据过期并 fail fast不自动重放 mutation;精确 Token Point exhaustion 被窄化为安全、不可重试、可持久恢复的产品错误,不透传原始上游正文 |
| `electron/coding-runtime/pi/{extension-host,subagent,write-lease}.ts` / `electron/main/background-lifecycle.ts` | 唯一显式 Makelore extension、交互、子 Agent、同项目写租约与后台运行租约 | child 并发 4、单次最多 8、禁止递归active/uncertain run 不因页面隐藏或确认超时被回收,所有 stop/replacement 必须有原因 |
| `electron/main/updater.ts` | 目标 feed 解析、electron-updater 生命周期与原始诊断 | 缺少稳定 manifest 保持错误;事件/Promise 重复失败按检查实例去重 |
| `src/components/settings/UpdateSettings.tsx` | 更新状态、重试与用户可读错误展示 | 只显示一条简洁中文提示;技术诊断统一回退到本地化通用文案 |
@@ -54,6 +54,7 @@
## Dependency Direction
- Renderer UI → Renderer API contract → Main Host routes → Main services → Works SquareRenderer 不反向读取 Main 凭据、文件系统或归档。
- Plugin sidebar/project links → Project Configuration Plugin Services sheet → existing Renderer stores → bounded Main Marketplace routes. Compatibility routes terminate in the same discover/mine/project tabs and do not create a second lifecycle.
- Hosted Plugin parent tool → frozen Registry adapter → Main `GameResourceClient` → fixed Works Square game-resource routes. Stable logical operation identity survives response loss and Main restart; ambiguous submission remains reviewable and is never converted into an automatic fresh mutation. Saving a result uses the existing bounded project path and project write lease.
- AI 编程 Renderer product Snapshot/commands → typed `/api/coding/*` Host API → Main Coding composition → target `CodingConversationRuntime` → shared Agent Server 内的目标 Pi 逻辑线程Pi Provider 请求再经 Main AI proxy 访问模型上游。Renderer 不持有 Pi wire、凭据或本地 runtime URL。
- Project configuration 决定产品分流Main release builder 生成 source/built/contract服务端独立重算和校验决定发布安全本地 `ProjectType` 不是授权结论。
@@ -72,6 +73,8 @@
- `runtime_url` 是一个客户端版本的迁移回退;删除前必须确认服务端和存量数据稳定提供 `play_url`
- Pi RPC confirmation timeout is an uncertainty boundary, not permission to release run/process/background ownership. Late success/failure/exit/abort must converge monotonically and exactly once; no accepted or uncertain mutation may be replayed automatically.
- Pi manual compaction in locked `0.84.2` does not emit `agent_settled`; correlated compact RPC success or an authoritative compaction failure must terminalize the compact operation without prematurely settling an ordinary prompt.
- Pi compaction is a model-context boundary, not a visible-history deletion boundary. Full active-branch hydration must keep compaction summaries private, and Renderer windowing must preserve the user's scroll anchor while prepending older nodes.
- Provider quota classification must remain exact and redacting: unrelated `403`/`429` failures cannot be reinterpreted as Token Point exhaustion, while reopened recognized failures must preserve only the stable product code and safe Chinese message.
- Shared parent logical threads do not consume one process lease each. Independent child Agents remain capped at 4 against the FIFO process budget of 8; stop failure must release child leases in `finally`.
- Provider/resource revisions apply before the next prompt for idle logical threads and after `agent_settled` for active runs. Same-account model changes may use `set_model`; cross-account changes rebuild only the target Conversation thread so old credentials never enter the new credential store.
- `electron/main/updater.ts` 的稳定源错误归一化必须保持窄化:只识别 Works Square 对应 manifest 的 404不得吞掉其他 feed/网络/签名错误Renderer 的脱敏边界不能取代 Main 原始日志。

View File

@@ -4,6 +4,18 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
## Integrated Through
- Plugin-navigation sources `b3f4166` and `e237941` from task
`20260831-consolidate-plugin-navigation-3d9a6c71` are integrated through
merge `a278ca3`. Coding history/quota source `d523b72` from task
`20260831-fix-history-quota-errors-6c2a91e4` is integrated through merge
`69832e0`, and assistant progress-preview source `8d878eb` from task
`20260831-show-progress-messages-a14f9c2d` is integrated through merge
`a8fd95f`. Project Configuration now owns the only visible Plugin Services
surface; Pi compaction no longer removes visible active-branch history;
recognized Token Point exhaustion remains safely actionable after reopen;
and collapsed process previews remain anchored to their first displayable
line. Historical source `b1f51be` remains explicitly excluded because
ADR-005 continues to retire the OpenMAIC Learning Player packaging chain.
- Human-authorized takeover task `20260831-promote-main-merge-5e9c7a31` completed
the already-started local `main` merge as
`03a9e866d4366e0a1cb416e26b424fe981071310`, recorded the transfer in
@@ -49,7 +61,9 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
the authenticated Marketplace/Library client, immutable Package Store, trusted
release verification, effective installed-plugin resolution, and frozen Pi worker
materialization; Renderer exposes Marketplace, My Plugins, and Project Plugins
projections without receiving credentials, paths, Admissions, or signed URLs.
projections only inside Project Configuration's single Plugin Services sheet,
without receiving credentials, paths, Admissions, or signed URLs. The former
standalone routes are compatibility redirects to the corresponding sheet tab.
Data Service remains system-included and consumes zero Token Points. R7 Standards
and Spec reviews passed with zero findings, and XMA-01 passed all twelve live groups
against real PostgreSQL and a signed-in packaged Windows client. The later
@@ -215,9 +229,11 @@ Canvas 侧栏提供“获取灵感”进入 Prompt Museum。列表、筛选、
Makelore 在会话恢复、登录和刷新后由 Electron Main 请求 Works `/api/auth/me`Renderer 只获得 Code、Canvas、Learning、Robot 四个布尔权限。缺失 `module_access` 或任一字段时默认开启;服务端 `design` 显式映射客户端 `painting`。被关闭的模块卡片置灰且不可点击,根路由、深层路由和别名路由均在 `MainLayout` 或模块初始化前阻断。Code provider 等待认证权限加载完成;权限查询返回终止性 `401` 时同时清理 Main 和 Renderer 会话。`/settings` 是全局设置,不受 Code 入口策略阻断。该机制只是客户端入口策略,不代替服务端 API 授权。
插件不再占用编程侧栏或独立产品页面。项目配置中的“插件服务”是唯一可见入口,并以 URL-backed 的“发现插件 / 我的插件 / 项目启用”标签分别承载 Marketplace、账号 Library/本机安装和当前项目启用配置;旧 `/plugin-marketplace``/my-plugins``/project-plugins` 路由只做兼容跳转。获取、设备安装、项目启用、Agent Skill 分配、运行授权和计费仍是独立生命周期,不因导航合并而自动推进。
AI 学习现在是已启用的运营精选项目目录,并继续受登录和 `module_access.learning` 控制。Renderer 通过 Main-owned Host API 获取分页项目卡片和 README 详情Markdown 支持 GFM、禁用原始 HTML。服务端发布时只校验图片 URL 为无凭据、默认端口、无 fragment 且当前 DNS 结果全部为公网地址的 HTTPS URL保留地址而不下载、识别格式、转码或镜像客户端仅为 README 图片节点启用直连,因此 SVG 和 Electron 支持的其他格式可直接显示单图失败不阻断详情。封面和历史发布媒体继续走受控路径。详情页的下载按钮打开系统保存对话框Main 将 ZIP 流式写入临时文件,只允许最多五跳同 Works origin 重定向,不校验 `Content-Length``archiveBytes`、实际流字节数或客户端大小上限,校验 SHA-256 和 ZIP 签名后原子保存Renderer 只接收 `saved``cancelled`。课程生成、进度、本地课程库、OpenMAIC player、Agent、ASR、课堂 runtime、Learning IPC 和 player artifact 打包已删除且没有兼容读取路径;历史课程数据保留但不再读取。服务端和客户端源码契约已完成,不代表生产部署或真实账号安装包联调已经完成。
AI 编程已经硬切到精确 pin 的 Pi `0.84.2`,不存在 OpenCode fallback 或双 runtime。project、Agent 与 Conversation 只在 `.makelore/project.json``.makelore/conversations.json` 使用本地 schema v2当前客户端不从 `.niancode``.opencode` 读取、迁移或删除项目元数据。Electron Main 按需启动一个长驻父 Agent Server每条 active/warm Conversation 在其中拥有独立 Runtime/Session/channel、credential store、extension context、generation/seq、Snapshot/Patch、model/thinking、队列、interaction 与错误状态Composer 在 lazy prepare 期间仍可编辑。Renderer 只通过 `/api/coding/*` 和 Snapshot-first/`patch-batch` SSE 消费产品中立合同gap/reconnect 只恢复目标 Conversationaccepted/uncertain mutation 不自动重放。未解析 Conversation 第一次选模先 validate 并持久化 resolved metadata再 prepare同账号模型切换使用 target `set_model`跨账号只重建目标逻辑线程。top-level 逻辑 turn 并发为 4warm idle logical-thread LRU 为 8independent child 进程并发为 4 并使用 FIFO 进程预算 8coding child 与 parent 共用项目 write lease。prompt/compact confirmation timeout 后仍保留 run/Agent-Server-or-child-process/background ownership迟到 success/failure/exit/abort 单调且 exactly-once 收敛,页面隐藏不会停止 active/uncertain run。线程级替换只使目标 generation 失效;整个 Agent Server 退出会统一使所有旧 channel 失效,但 Main/Renderer 存活且下次恢复只重启一个 Server。Pi `0.84.2` 手动 compact 不发 `agent_settled`,由 correlated compact RPC 结果终结。父 Provider credential 只进入选中逻辑线程的内存 credential storechild 凭据只进入该短命进程;确定性的 Works user-context 缺失会失效 gateway credential、fail fast、不重放并投影固定 Provider-auth 错误,不归类为 Pi crash。真实 Provider 验证仍为用户明确接受的未验证风险macOS x64/arm64 与 native non-WSL Linux 也未通过平台发布门禁。
AI 编程已经硬切到精确 pin 的 Pi `0.84.2`,不存在 OpenCode fallback 或双 runtime。project、Agent 与 Conversation 只在 `.makelore/project.json``.makelore/conversations.json` 使用本地 schema v2当前客户端不从 `.niancode``.opencode` 读取、迁移或删除项目元数据。Electron Main 按需启动一个长驻父 Agent Server每条 active/warm Conversation 在其中拥有独立 Runtime/Session/channel、credential store、extension context、generation/seq、Snapshot/Patch、model/thinking、队列、interaction 与错误状态Composer 在 lazy prepare 期间仍可编辑。Renderer 只通过 `/api/coding/*` 和 Snapshot-first/`patch-batch` SSE 消费产品中立合同gap/reconnect 只恢复目标 Conversationaccepted/uncertain mutation 不自动重放。Session hydration 沿完整 active branch 投影可见历史Pi compaction 只改变模型上下文并保持 summary 私有Renderer 首次挂载最近 120 个节点,向上滚动时按 100 个节点追加更早内容并补偿新增高度以保持阅读锚点。折叠的 thinking、助手过程说明与工具输出固定展示第一条可见内容和首个非空行横向偏移保持为零展开后仍显示完整内容。未解析 Conversation 第一次选模先 validate 并持久化 resolved metadata再 prepare同账号模型切换使用 target `set_model`跨账号只重建目标逻辑线程。top-level 逻辑 turn 并发为 4warm idle logical-thread LRU 为 8independent child 进程并发为 4 并使用 FIFO 进程预算 8coding child 与 parent 共用项目 write lease。prompt/compact confirmation timeout 后仍保留 run/Agent-Server-or-child-process/background ownership迟到 success/failure/exit/abort 单调且 exactly-once 收敛,页面隐藏不会停止 active/uncertain run。线程级替换只使目标 generation 失效;整个 Agent Server 退出会统一使所有旧 channel 失效,但 Main/Renderer 存活且下次恢复只重启一个 Server。Pi `0.84.2` 手动 compact 不发 `agent_settled`,由 correlated compact RPC 结果终结。父 Provider credential 只进入选中逻辑线程的内存 credential storechild 凭据只进入该短命进程;确定性的 Works user-context 缺失会失效 gateway credential、fail fast、不重放并投影固定 Provider-auth 错误,不归类为 Pi crash。精确的 `403 token_point_balance_exhausted` / `词元点数余额不足` 上游响应会在 Main 内归类为不可重试的配额耗尽Renderer 只收到稳定 `CODING_PROVIDER_QUOTA_EXHAUSTED` 与安全中文提示;重开会话仍保留该提示,不暴露上游 request id 或原始错误正文。真实 Provider 验证仍为用户明确接受的未验证风险macOS x64/arm64 与 native non-WSL Linux 也未通过平台发布门禁。
Updater 仍由 Electron Main 选择目标 feed、记录原始诊断并保持失败语义。正式稳定源缺少对应平台 manifest 时设置页只显示一条简洁中文提示并允许重试不把缺包误报为已是最新版也不向普通界面暴露堆栈、URL、路径或错误码签名产物发布和真实升级安装仍属于外部 Release Gate。
@@ -225,6 +241,12 @@ Robot 绑定设备默认先显示“引导配网 / 已有激活码”路径选
## Recently Completed
- 2026-09-01: Integrated the consolidated Plugin Services navigation, complete
active-branch Coding history with scroll-anchor preservation, narrow Token Point
quota feedback, and stable first-line process previews. Combined typecheck,
focused/full unit tests, lint, Vite/Electron builds, and five focused Electron
E2E scenarios passed. The obsolete Learning Player packaging branch remains
excluded by explicit human confirmation and ADR-005 remains authoritative.
- 2026-08-31: Integrated the provider-neutral `makelore.game-resource` hosted Plugin
client with fetched `origin/main`. Generic schema-2 `platform_hosted` packages now
materialize frozen Skill/tool snapshots only for eligible parent Pi logical threads;
@@ -308,4 +330,4 @@ Robot 绑定设备默认先显示“引导配网 / 已有激活码”路径选
## Last Updated
2026-08-31
2026-09-01

View File

@@ -8,7 +8,7 @@
- Worktree: /Users/inmanx/Documents/makelore
- Base commit: 9ed70ba925a7e544f17bf5b418846df9d4145a2a
- Owner: codex
- Status: Planning
- Status: Ready for finalization
## Scope
@@ -54,8 +54,13 @@
`http://localhost:5173/` and Electron Main owns Host API port `13210`.
- Exactly one local branch remains outside `main`:
`codex/learning-player-release-fix@b1f51be`. Its five-file patch restores the
retired OpenMAIC Learning Player packaging supply chain, contradicts ADR-005,
and requires an explicit product-direction decision before integration.
retired OpenMAIC Learning Player packaging supply chain and contradicts
ADR-005. On 2026-09-01 the user explicitly confirmed that this branch must
remain excluded, so ADR-005 stays authoritative and the branch is preserved
unchanged as historical local state.
- Promoted the accepted Plugin Services, complete visible history, quota
feedback, and first-line process-preview facts into `README.md`,
`current-state.md`, and `module-map.md`; no accepted ADR was reversed.
## Verification
@@ -75,21 +80,22 @@
- Runtime probes: Vite returned HTTP 200; the Host API returned its expected
unauthenticated HTTP 401 challenge; Node PID 39837 and Electron PID 39847
listen on ports 5173 and 13210 respectively.
- `check_project_docs.py`: passed.
- `git diff --check`: passed after canonical promotion.
- `check_doc_drift.py --task-id 20260901-integrate-all-local-4d7a9c21`:
correctly blocked this intake task because nine immutable source-task
records entered through the merges after its base. No source record was
edited; a successor Integration Gate will use this complete intake as its
base and perform the final task-aware certification.
## Follow-ups
- Obtain the required human choice for the ADR-005 conflict. If the historical
Learning branch remains excluded, finalize canonical documentation around
the three accepted product changes and close the Integration Gate. If it is
explicitly accepted, first reverse ADR-005 and reconcile the branch against
the current Learning boundary rather than taking a mechanical merge side.
- Open a fresh finalization Integration Gate based after these source-task
merges. This task intentionally introduced foreign immutable task records,
so the task-aware drift checker must certify the final tree from the
post-intake base rather than misattribute those records to canonical edits.
## Promotion Candidates
- Promote the Plugin Services source task into `current-state.md` and
`module-map.md`: Project Configuration is the sole visible plugin surface,
with discover/mine/project tabs and compatibility-only standalone routes.
- Promote the Coding history/quota source task into `README.md` and
`current-state.md`: compaction may bound model context without removing the
visible active-branch history, and recognized Provider quota failures remain
actionable after reopen.
- Applied to `README.md`, `current-state.md`, and `module-map.md`; no remaining
promotion candidate is known.