projectkeeper 0.0.0-stage → 1.0.0

package/README.zh-CN.md

@@ -0,0 +1,285 @@
+# ProjectKeeper
+
+**AI 写代码越来越快，但你还知道它做出来的是不是你想要的吗？**
+
+ProjectKeeper 把你说过的要求、改过的决定和 AI 实际完成的工作放在一张图上，帮你发现偏差，让下一个 agent 接得上，项目做到一半也能接手。接手由你自己的 agent 来做：照项目本来的样子读一遍，填一张表；之后一个常驻的 agent 每天跟着项目更新这张图。
+
+- **以你说过的话为准。** 你的原话一字不改地留着，带着是在哪段会话里说的。文档和你的话对不上了、你要的东西半路没了、多出了你没要过的工作，ProjectKeeper 都会告诉你。
+- **做到一半的项目，随时能交接。** 把它指向项目文件夹：文档、git 历史、代码和 agent 会话整理成一张图；一条命令，就把某项工作的上下文交给下一个 agent。
+
+[English](README.md) · 简体中文
+
+[![许可证：MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)
+![Node.js 24 及以上](https://img.shields.io/badge/node-%E2%89%A5%2024-brightgreen)
+[![CI](https://github.com/feiyanglyy-stack/ProjectKeeper/actions/workflows/ci.yml/badge.svg)](https://github.com/feiyanglyy-stack/ProjectKeeper/actions/workflows/ci.yml)
+![本地运行：不用账号，不传遥测](https://img.shields.io/badge/local--first-no%20account%2C%20no%20telemetry-success)
+
+![一个真实项目的故事地图：最上面是 owner 的原话和产品，往下是目标和产品区域，两代旧计划收成两条，再往下是现行计划里的每一项工作](docs/images/hero-story-map.png)
+
+*一个真实项目，一屏看完：owner 要的是什么、目标和产品区域、两代旧计划、现行计划里的工作。每个对象点开都能看到出处。*
+
+## 为什么要有它
+
+让 AI 连续开发一个软件，很容易走到这一步：对话越来越多，计划不断修改，agent 换了好几轮。每个 agent 都说完成了任务，却没人能完整说清：最初要的是什么、后来改了什么、最后到底做成了什么样。答案其实都在——在文档里、提交说明里、没人会再翻的会话记录里。
+
+ProjectKeeper 就像一个工程档案员。它不替 agent 写代码，而是把每一次要求、每一次改动和实际完成的工作理清楚。哪里对不上，它会指出来；换了 agent，它能把来龙去脉交给下一个。
+
+项目做到一半才请它来也不晚：它把以往的会话、文档和提交都翻一遍，告诉你每一版要求是什么、后来改成了什么、现在做成的是哪一版。这些都在你自己的机器上完成。
+
+## 你能得到什么
+
+- **整个项目在一张图上。** 你说过想要什么、目标、产品区域、计划，每一项工作各在其位。
+- **每项工作到底经过了什么。** 派出、交付、审查、修复、合并，每一步都带着它依据的提交、报告或判定；Keeper 自己推断的标 `Inferred`。
+- **一个决定是怎么来的。** 你的原话，一字不改，带着是在哪段会话里说的；还有把这个决定落下去的文档和提交。
+- **旧计划后来怎么样了。** 上一代计划里的每一项各有去向：接着做了、挪走了、推后了，还是放弃了。
+- **哪些事要你拿主意。** 需要你决定的 note 会给出几个选项；审查没过、又没人接的事（送回）可以直接复制给 agent。
+- **给下一个 agent 的上下文。** 一条命令，就把某项工作的上下文交给它：这项工作为了什么、怎么走到今天、你这个项目的规矩、代码在哪。
+
+而且它会一直跟着：接管完之后，按你定的时间每天整理一轮，或者你按一下 `Follow up`。
+
+## 跑完第一遍
+
+第一遍读文档、git 历史、代码结构和你的 agent 会话，填出三个视图。
+
+![第一遍之后的 Graph 视图](docs/images/first-pass-01-story-map.png)
+
+*Graph：最上面是你的原话和产品，横着是目标和区域，旧计划收成横条，现行计划的工作落在各自的格子里。*
+
+![第一遍之后的 List 视图，展开了一个区域](docs/images/first-pass-02b-list-module-open.png)
+
+*List：展开一个区域。左边是计划了什么，右边是实际发生了什么——进行中、在哪个提交里合并了、交付了但没有检查记录。*
+
+![第一遍之后的 Code 视图](docs/images/first-pass-03-code-territories.png)
+
+*Code：哪块代码属于哪个产品区域、是哪些工作做出来的、有多少测试、现行计划还用不用它。*
+
+**实测：** 这一遍用 DeepSeek 跑了大约 50 分钟，花了大约 11 元人民币（约 1.5 美元）。被整理的项目就是 ProjectKeeper 自己的工作仓库：文档加代码大约 1,000 个文件（约 470 份 Markdown 文档、400 个源码文件，约 21.7 万行），大约 750 次提交，22 段 agent 会话。
+
+## 加深之后
+
+加深是带着问题去挖历史，并且自己查一遍自己的结论。同一个项目上，加深又用了 71 分钟。
+
+![一项工作，连同它的步骤和证据](docs/images/deepened-02-work-item-steps-and-evidence.png)
+
+*一项工作，下面挂着它的步骤——检查、派出、交付、合并；旁边是它改过的代码，以及它经过的提交和审查判定。*
+
+![一个区域的需求、设计和决定，以及其中一个决定的来历](docs/images/deepened-01-intent-chain-and-where-a-decision-came-from.png)
+
+*一个决定是怎么来的：一个区域的需求、设计和决定列在一起；点开其中一条，能看到它是哪天定的、哪些提交把它落了下去。*
+
+![上一代计划，每一项划掉，旁边是接着做它的现行工作](docs/images/deepened-03-earlier-generation-what-its-items-became.png)
+
+*旧计划后来怎么样了：上一代的每一项都划掉了，旁边写着现在是哪一项接着在做。*
+
+![一条要 owner 拿主意的 note，带选项](docs/images/deepened-05-note-for-the-owner-with-options.png)
+
+*要你拿主意的 note：问的是什么、Keeper 怎么看、为什么要紧、三个选项各自会带来什么，以及带出处的事实。*
+
+![每一轮、每个模型的用量](docs/images/deepened-06b-keeper-usage-by-model.png)
+
+*每一轮用了多少、哪个模型承担了哪些步骤。图上的美元数是按标价估的，这一轮实际扣的钱比它少（见[跑一轮要花多少](#跑一轮要花多少)）。*
+
+![从地图到一项工作，到它的步骤，再到它改的代码](docs/images/map-to-work-item-to-steps-to-code.gif)
+
+*从地图，到一项工作，到它经过了什么，再到它改了哪些代码。*
+
+## 不用 key 先看看
+
+```sh
+npm run demo
+```
+
+它会生成一个虚构的项目——Papertrail，一个人用的稍后读清单——已经整理好，在 `http://127.0.0.1:4880/` 打开。不需要 key，不调模型，不联网；demo 里 Keeper 的回答是预先写好的。它写的东西都在系统临时目录下的一个文件夹里。
+
+## 四套界面
+
+工作台带四套主题，在顶栏的 `Theme` 里切换。下面是 demo 项目在每套主题下的样子。
+
+<table>
+<tr>
+<td width="50%"><img src="docs/images/theme-a1-walnut-workshop.png" alt="demo 项目的 Graph，Walnut Workshop 主题"><br><b>Walnut Workshop</b>（默认）</td>
+<td width="50%"><img src="docs/images/theme-b1-peacock-and-brass.png" alt="demo 项目的 Graph，Peacock &amp; Brass 主题"><br><b>Peacock &amp; Brass</b></td>
+</tr>
+<tr>
+<td width="50%"><img src="docs/images/theme-d2-warm-clay.png" alt="demo 项目的 Graph，Warm Clay 主题"><br><b>Warm Clay</b></td>
+<td width="50%"><img src="docs/images/theme-i1-task-console.png" alt="demo 项目的 Graph，Task Console 主题"><br><b>Task Console</b></td>
+</tr>
+</table>
+
+同一个列表里的 `Factory` 是不带主题的内置外观。
+
+## 快速开始
+
+需要 Node.js 24 及以上，以及 git；系统是 Windows 或 macOS。在 Mac 上，git 随 Xcode 命令行工具安装（`xcode-select --install`）；Homebrew 的 `node` 比这里测试过的 24 要新：见 [Mac 上需要什么](docs/getting-started.md#on-a-mac)。
+
+```sh
+git clone https://github.com/feiyanglyy-stack/ProjectKeeper.git && cd ProjectKeeper
+npm ci
+npm start
+```
+
+也可以不克隆，直接从 npm 装：`npm install -g projectkeeper`，然后 `projectkeeper serve`；本页写 `npx pk` 的地方，换成 `projectkeeper`。
+
+然后接手你的项目，有两种方式。
+
+**用你自己的 agent（推荐）。** Claude Code、Codex 或你在用的其他 agent 读项目，填那张表：
+
+```sh
+npx pk takeover --project <你的项目文件夹> --prepare
+```
+
+它会在 ProjectKeeper 自己的目录里（不会写进你的项目）摆好三个文件夹，各附一份说明：
+- 一个给只读你在以往会话里说过的话的 agent；
+- 一个给只读项目副本的 agent；
+- 一个给把两边合起来的 main agent。
+
+用你的 agent 把这三步跑完，再照命令打印出的那条 `pk import` 把表导进来。用 Codex 的话，把 `--prepare` 换成 `--run codex`，三步会自己跑完，表核对无误就自动导进来。然后打开 `http://127.0.0.1:4870/` 就能看到。agent 怎么填这张表：见[模板](template/FILLING-IN.md)。
+
+**用 Keeper 和你的 key。** 打开 `http://127.0.0.1:4870/`，然后点四下：
+
+1. **Add project**——起个名字，填上项目所在的文件夹（直接输入路径，或点 `Browse…` 从列表里选）。这时什么都还没开始跑。
+2. **加一把 key**——在随后打开的 Keeper 页上，`Model provider` 里：选服务商，粘贴 key，`Save`。
+3. **选一个深度**——`Full`、`Focused` 或 `First picture only`。
+4. **Start。**
+
+先出第一份可用的全貌；选了加深的话，接着做加深。细节见 [Getting started](docs/getting-started.md)。
+
+不管用哪种方式接手，日常更新都要一把 key：项目变了，Keeper 用它把图跟着更新。
+
+## 模型与 key
+
+key 你自己带。底下的模型库（[pi](https://github.com/earendil-works/pi)）列了四十来家服务商，我们实际跑过的是 **DeepSeek**（`deepseek-v4-pro`、`deepseek-flash`）和**智谱 GLM**（`glm-5.3`、`glm-5.3-flash`）。你保存的 key 只留在本机 ProjectKeeper 自己的文件夹里，保存之后界面上不会再显示。一轮里的每一步可以各用各的模型；一把 key 额度用完了，备用的 key 会接上：见 [Models and keys](docs/models-and-keys.md)。
+
+**订阅登录：** Claude 的 Pro、Max 订阅跑不了 Keeper：Anthropic 只许在 Claude Code 和 claude.ai 里用这种登录，请改用 Claude Console 的 API key。ChatGPT（Codex）、Kimi Coding、GitHub Copilot 的订阅能经 pi 的登录接上，都还没实测：见 [Subscriptions](docs/models-and-keys.md#subscriptions)。
+
+## 跑一轮要花多少
+
+**用你自己的 agent 接手**，花的是那个 agent 自己的订阅额度。在 ProjectKeeper 自己的工作仓库上，Codex 跑完三步约 27 分钟：
+- 读原话和读项目两路同时跑，约 18 分钟；
+- main agent 再跑 8 分钟。
+
+填出来的表有：你要的事 75 件，决定 33 条加边界 7 条，工作 36 项，你和项目对不上的地方 18 处。
+
+**每天的跟进**用你的 key；没有新东西的日子不调用模型。
+
+**由 Keeper 接手**（第一遍加一次完整加深），同一个项目一共实测了四次：
+
+| 模型搭配 | 用时 | 花费 |
+|---|---|---|
+| DeepSeek：全用 flash，最后的抽查用 pro | 126 分钟 | 实扣 29 元（约 4 美元） |
+| DeepSeek：主 agent 和加深的子 agent 用 pro，其余用 flash | 122 分钟 | 实扣 57 元（约 8 美元） |
+| 智谱 GLM-5.3 做主 agent，其余用 GLM-5.3-flash | 198 分钟 | 按标价 19 美元 |
+| 全用智谱 GLM-5.3 | 200 分钟 | 按标价 67 美元 |
+
+这是同一个项目上的四次运行，只能粗略横向比一比，不是评测。几次运行之间程序改过（两次 GLM 是较早的版本）；全 flash 那一次的主 agent，还在它整理的项目里读到了上一次运行的问题清单。
+
+- **只跑第一遍**，用 DeepSeek：大约 50 分钟；pro 做主 agent 约 11 元，全用 flash 约 10 元。
+- **GLM 如果用的是 Coding Plan 订阅**，实际花费远低于标价。按维护者自己的说法：GLM-5.3 跑第一遍，大约用掉团队初级成员 5 小时额度的一半；加深大约用掉一个 5 小时额度；每天的 follow up 基本看不出额度变化；全用 flash 的话，整个跑完大约是一个 5 小时额度的三分之一。
+- **Usage 页上的金额是估算。** 它拿记录下来的 token 数去乘一张标价表；用 pro 的那次 DeepSeek 运行，页面显示 14.48 美元，账户实际扣了 57 元。
+
+每一次跑对了什么、漏了什么：见 [Cost and quality](docs/cost-and-quality.md)。
+
+## 它不做什么，以及隐私
+
+- **它不改你项目里的文件。** 它只写自己的文件夹（`~/.projectkeeper`）。在你的项目里，它只写一个属于它自己的文件夹，而且要你先授权。
+- **只监听 `127.0.0.1`。** 不用账号，自己也不传任何遥测。
+- **会离开你机器的东西**，是发给你所选模型服务商的内容：提示词里带着你项目的文字——文档、代码、提交说明，以及你在 agent 会话里说过的话。
+- **它不写代码，不跑你的测试，也不管工单。** 它只读，然后把读到的告诉你，每句话都带出处。
+
+更多见 [Privacy](docs/privacy.md)。
+
+## 给你的 agent：`pk`
+
+工作台开着的时候，agent 可以用一条命令读到同一份全貌。下面是 demo 项目上两段真实的输出，`…` 处有省略：
+
+```text
+$ pk context --work T-18
+# Context for Incoming agent · Work: T-18 Search index incremental rebuild 增量重建 · Kind: Implement
+…
+## Owner's words
+What the owner said that this work traces up to, word for word:
+…
+- `ow_search_fast` · the owner, 2026-09-16 [2]:
+  “搜索要在一秒内出结果，不然我不会用”
+…
+## Open problems
+- The receipt claims a one-minute background refresh; the code does not have it.
+- Is the one-minute refresh claim measured anywhere?
+…
+```
+
+```text
+$ pk get sb_search_refresh
+# Send-back · sb_search_refresh
+Where: Search index incremental rebuild 增量重建 (thread_search_index)
+What: Batch 2 says the index refreshes every minute; the review could not confirm it from the code, and batch 2 was signed off anyway.
+Send back to: Work · Reopen T-18: make the index refresh in the background, or correct the receipt.
+Status: Suggested · Open
+…
+```
+
+用 MCP 接工具的客户端（Claude Desktop、Cursor 等）可以用 `pk mcp`：它把同样这几条命令做成一个本地 MCP 服务，配置见 [As an MCP server](docs/pk.md#as-an-mcp-server)。
+
+全部用法，以及怎样对着 demo 跑这些命令：见 [The `pk` command](docs/pk.md)。
+
+## 它是怎么工作的
+
+```mermaid
+flowchart LR
+  subgraph P["你的项目，照原样读"]
+    D["文档与计划"]
+    G["Git 历史"]
+    C["代码"]
+    S["Agent 会话"]
+  end
+  subgraph T["接手：由你自己的 agent 来做"]
+    O["你的原话，从会话里读"]
+    R["项目，从副本里读"]
+    M["main agent：合并两边，对不上的地方写 note"]
+    O --> M
+    R --> M
+  end
+  subgraph K["ProjectKeeper，在你的机器上"]
+    L["账本：程序记下有什么、各在什么时候"]
+    C2["pk check、pk import：拿项目核对这张表"]
+    U["日常：Keeper 在这张表上接着更新"]
+  end
+  P --> L
+  P --> T
+  M --> C2
+  C2 --> U
+  K --> W["浏览器里的工作台"]
+  K --> A["pk，给你的 agent"]
+```
+
+先由程序把「有什么、各在什么时候」记成账本：每次提交、每个文档版本、每个编号、每段会话。这一步不用模型。接着由你自己的 agent 用它自己的方式读项目，填好一张表。程序拿项目核对这张表：每个编号、每处出处、每句原话都要逐字对上，然后画出来。之后项目每有变化，Keeper 就在同一张表上接着更新，照样过同一道核对。程序数得清、查得了的，都交给程序；模型的注意力留给判断。
+
+Keeper 也能用你的 key，自己分轮次接手一个项目。详见 [How the Keeper works](docs/how-the-keeper-works.md)。
+
+## 和同类工具比
+
+画代码结构图的工具（比如 Understand-Anything）告诉你代码之间怎么连；ProjectKeeper 画的是意图和工作——想要什么、计划了什么、做了什么——代码挂在它服务的产品区域下面。会话记忆类工具（比如 claude-mem）从装上那天起记录 agent 做的事；ProjectKeeper 接手的是已经存在的一切，连同历史。规格和任务类工具（比如 OpenSpec、Backlog.md）要你和 agent 按它们的格式来写；ProjectKeeper 不要你多写任何东西。它读项目里本来就有的材料，整理出来给人翻，也给 agent 查。
+
+## 现状与局限
+
+- **v1.0。** 它会出错，同一个项目每次跑出来也不完全一样；每句话都连着出处，你可以自己核对。四次实测以及各自漏了什么，见 [Cost and quality](docs/cost-and-quality.md)。
+- **Windows 和 macOS。** ProjectKeeper 是在 Windows 上做出来的，也每天在 Windows 上用。它也能在 macOS 上运行：测试套件在 GitHub 的 macOS 运行器上通过，但还没有人在 Mac 上日常用过，难免有粗糙的地方——欢迎告诉我们它在你的 Mac 上表现如何。Linux 暂不支持。
+- **Mac 上的文件名。** 只差大小写的两个名字，或者只差 Unicode 写法的两个名字（带重音的字母、韩文、日文假名的合成与分解两种形式），ProjectKeeper 都当作同一个名字，和 Mac 常用的卷一样。如果卷被格式化成区分大小写的，这样的两个文件会被当成一个。
+- **路径很长的项目。** 项目里再深的文件都能读。但在 Windows 上，项目自身的路径有上限，git 和 Windows 的长路径设置都解除不了：超过 246 个字符，git 打不开这个仓库（文件照读，历史读不到，`Project scope` 里会写明）；超过 251 个字符，Keeper 无法在这个目录里工作。请把这样的项目挪到短一些的路径下。
+- **会话只读 Claude Code 和 Codex 的。** 其他 agent 的会话暂时不读。
+- **界面是英文的，内容跟着你项目的语言走。** 截图来自一个中文项目。
+- **名字。** ProjectKeeper 开发期间的名字是 ContextKeeper；截图里它整理的正是它自己的项目，那个项目用的还是这个名字。
+
+## 文档
+
+文档目前只有英文：[Getting started](docs/getting-started.md) · [Concepts](docs/concepts.md) · [Models and keys](docs/models-and-keys.md) · [How the Keeper works](docs/how-the-keeper-works.md) · [Cost and quality](docs/cost-and-quality.md) · [The `pk` command](docs/pk.md) · [Privacy](docs/privacy.md) · [FAQ](docs/faq.md) · [Architecture](docs/architecture.md)
+
+## 参与
+
+欢迎提 issue 和 pull request：见 [CONTRIBUTING.md](CONTRIBUTING.md)。版本变化记在 [CHANGELOG.md](CHANGELOG.md)。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。`ui/themes/` 下的主题不在这份许可证之内：见 [ui/themes/LICENSE.md](ui/themes/LICENSE.md)。第三方材料：[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
+
+使用 [Claude Code](https://claude.com/claude-code) 构建。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,53 @@
+# Third-party notices
+
+ProjectKeeper's own code is under the MIT licence (see [LICENSE](LICENSE)). This file lists the third-party material
+that is redistributed inside this repository. Packages that npm installs (`package.json`, `package-lock.json`) are not
+redistributed here; each carries its own licence in `node_modules`.
+
+## pi-ai (`@earendil-works/pi-ai`), versions 0.87.1 and 0.85.0 — MIT
+
+Where: `patches/pi-ai-0.87.1.ts` and `patches/pi-ai-0.85.0.ts`.
+
+These two files describe the changes ProjectKeeper makes to the installed copy of pi-ai (`patches/README.md` says what
+the changes do). To find the places to change, each file quotes short passages of pi-ai's distributed JavaScript
+(`dist/utils/json-parse.js`, `dist/utils/validation.js` and six files under `dist/api/`) next to the text that replaces
+them. Those quoted passages are pi-ai's, used under its licence:
+
+- Package: `@earendil-works/pi-ai`, from <https://github.com/earendil-works/pi> (`packages/ai`)
+- Licence: MIT
+
+```
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## The themes under `ui/themes/` — not open source
+
+The four themes (`a1`, `b1`, `d2`, `i1`) were made for another product, WorkflowKeeper, by the same author, and are
+shipped with ProjectKeeper as they are. They are not covered by the MIT licence: see
+[ui/themes/LICENSE.md](ui/themes/LICENSE.md).
+
+## Colour-vision simulation matrices
+
+`scripts/palette-check.py` (a development check, not part of the running product) uses the protanopia and deuteranopia
+simulation matrices published in Machado, Oliveira and Fernandes, "A Physiologically-based Model for Simulation of Color
+Vision Deficiency", IEEE Transactions on Visualization and Computer Graphics, 2009.

package/bin/pk.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// pk, also installed as projectkeeper — the ProjectKeeper command (src/cli.ts says what it does). This file is plain
+// JavaScript so that it runs wherever npm puts it: from a clone, after `npm link`, through `npm exec` / `npx`, or installed as a package — where Node will
+// not strip types under node_modules by itself, and bin/strip-types.mjs does it for ProjectKeeper's own sources.
+if (import.meta.url.includes('/node_modules/')) await import('./strip-types.mjs');
+await import('../src/cli.ts');

package/bin/postinstall.mjs

@@ -0,0 +1,5 @@
+// After `npm ci` / `npm install`: apply ProjectKeeper's patch to the installed pi-ai (patches/README.md). Plain
+// JavaScript for the same reason as bin/pk.mjs: installed as a package, the script it runs sits under node_modules.
+if (import.meta.url.includes('/node_modules/')) await import('./strip-types.mjs');
+const { applyPiStreamingPatch, label } = await import('../scripts/apply-pi-streaming-patch.ts');
+console.log(`${label}:`, await applyPiStreamingPatch());

package/bin/strip-types.mjs

@@ -0,0 +1,28 @@
+// Node runs ProjectKeeper's TypeScript sources as they are, by stripping the types — except for files under a
+// node_modules directory, which it refuses. So when ProjectKeeper is installed as a package (not run from a clone),
+// this module does the same stripping for ProjectKeeper's own .ts files, and for nothing else. It is loaded by
+// bin/pk.mjs and bin/postinstall.mjs, and handed on to the worker thread and the child process ProjectKeeper starts
+// (src/util/own-ts.ts). In a clone it is never loaded.
+import * as nodeModule from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const root = new URL('../', import.meta.url).href;
+const own = (url) => url.startsWith(root) && !url.slice(root.length).includes('node_modules/') && url.endsWith('.ts');
+
+if (typeof nodeModule.registerHooks !== 'function' || typeof nodeModule.stripTypeScriptTypes !== 'function') {
+  throw new Error(`ProjectKeeper needs Node.js 24 or later to run from an installed package (this is ${process.version}).`);
+}
+// Node warns once that stripTypeScriptTypes is experimental; from a clone the same stripping runs without a word, so
+// an installed command says nothing about it either. Every other warning goes through.
+const emitWarning = process.emitWarning;
+process.emitWarning = function (warning, ...rest) {
+  if (String(warning?.message ?? warning).includes('stripTypeScriptTypes')) return;
+  return emitWarning.call(this, warning, ...rest);
+};
+nodeModule.registerHooks({
+  load(url, context, nextLoad) {
+    if (!own(url)) return nextLoad(url, context);
+    return { format: 'module', shortCircuit: true, source: nodeModule.stripTypeScriptTypes(readFileSync(fileURLToPath(url), 'utf8')) };
+  },
+});

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "projectkeeper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "A resident agent that reads a software project as it is — documents, git history, code and agent sessions — and keeps a browsable picture of what was planned, decided and done. Local-first; bring your own model key.",
+  "keywords": [
+    "ai-agents",
+    "coding-agents",
+    "project-context",
+    "context-engineering",
+    "project-management",
+    "developer-tools",
+    "claude-code",
+    "codex",
+    "local-first",
+    "project-graph",
+    "decision-records"
+  ],
+  "homepage": "https://github.com/feiyanglyy-stack/ProjectKeeper#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/feiyanglyy-stack/ProjectKeeper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/feiyanglyy-stack/ProjectKeeper/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "projectkeeper": "bin/pk.mjs",
+    "pk": "bin/pk.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-helpers.ts",
+    "ui/",
+    "skills/",
+    "template/",
+    "patches/",
+    "scripts/apply-pi-streaming-patch.ts",
+    "THIRD_PARTY_NOTICES.md",
+    "CHANGELOG.md"
+  ],
+  "mcpName": "io.github.feiyanglyy-stack/projectkeeper",
+  "scripts": {
+    "postinstall": "node bin/postinstall.mjs",
+    "start": "node src/cli.ts serve",
+    "demo": "node scripts/demo.ts",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@colbymchenry/codegraph": "1.6.0",
+    "@earendil-works/pi-agent-core": "0.87.1",
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "cytoscape": "3.34.3",
+    "cytoscape-dagre": "4.0.1",
+    "dagre": "0.8.5",
+    "typebox": "1.3.7",
+    "typescript": "5.9.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.5"
+  }
+}

package/patches/README.md

@@ -0,0 +1,111 @@
+# pi-ai patches: streaming argument repair and complete arguments only
+
+`npm ci` / `npm install` runs `scripts/apply-pi-streaming-patch.ts` (through `bin/postinstall.mjs`). The patch targets
+pi-ai **0.87.1** in every lockfile installation location (currently two copies); where ProjectKeeper is installed as a
+package and has no lockfile of its own, in the copy pi-coding-agent loads and the copy ProjectKeeper itself would load.
+It checks package versions, whole-file SHA-256 hashes and unique replacement contexts
+before writing any file. Re-running is safe. A changed package or unexpected source
+fails installation with an explicit error; upgrading pi requires reviewing this patch.
+An installation with `--ignore-scripts` must run the postinstall command explicitly.
+
+The patch has two parts, added one after the other. In the patched files their comments
+are marked `ProjectKeeper AO` (delta parsing) and `ProjectKeeper AX` (complete arguments
+only); the letters are only the names of the markers.
+
+Each file's replacements apply in order, and a later generation only appends its own.
+An installation that an earlier generation patched (for example delta parsing only) is
+therefore still recognised: the script undoes whatever replacements it finds, accepts the result
+only if it has the upstream hash, and applies the whole current list. So after pulling
+a newer patch, `node scripts/apply-pi-streaming-patch.ts` (or `npm ci`) brings an
+existing `node_modules` up to date. A file changed any other way is refused; `npm ci`
+restores the upstream files.
+
+`pi-ai-0.85.0.ts` is retained as the exact patch manifest for a 0.85.0 rollback.
+The installer and baseline benchmark use only `pi-ai-0.87.1.ts`; the older
+manifest is not applied to a 0.87.1 installation.
+
+## Delta parsing (marker `AO`)
+
+Only tool argument **delta** parsing changes: each tool-call object has a weakly held
+last parsed length. After its first snapshot, parse again at >= 1,024 characters and
+at least double that length thereafter. Other deltas retain the last valid snapshot
+and still emit the complete raw delta. Total prefix length processed is O(N), instead
+of O(N²/k). State is per object, so streams and interleaved tool calls cannot mix.
+No scratch state is added to tool arguments or session files.
+
+## Complete arguments only (marker `AX`): a tool call runs only on arguments that arrived as complete JSON
+
+Upstream, every native provider parses the complete buffer at tool end with
+`parseStreamingJson`, which falls back to `partial-json` when the buffer does not
+parse. That fallback completes a cut-off buffer into a shorter value that can pass the
+tool's validation and run: a check run saw 103 characters of markdown saved as 15, with
+the job `Done`; with the built-in `write` it would write a truncated file.
+
+This part replaces those final parses with `finalizeStreamingToolArguments` (in
+`dist/utils/json-parse.js`). It parses with upstream's `parseJsonWithRepair`, so raw
+control characters and invalid escapes are repaired exactly as before, and an empty
+buffer is still `{}`. When that fails — the text ends inside a string or before its
+brackets close, or anything else keeps it from being one JSON value — the call is
+marked with `Symbol.for("projectkeeper.pi-ai.incompleteToolArguments")`. The
+`partial-json` value is still stored as the arguments, so the Keeper view and the
+replayed conversation show what arrived; a symbol key is never serialized into session
+files or provider requests.
+
+`validateToolArguments` (in `dist/utils/validation.js`) refuses a marked call before
+it validates anything. pi-agent-core validates every tool call through it, whatever
+the tool — the built-ins, ProjectKeeper's `pk_*` tools, an extension's tools — and
+before any `tool_call` hook, so nothing runs. The refusal is the tool result the model
+gets, and it leads with what the model must do:
+
+> Tool call "write" was not executed: its arguments did not arrive as complete JSON,
+> so they may have been cut off. Nothing was run; send the call again with the complete
+> arguments. (200 characters arrived; Unterminated string in JSON at position 200)
+
+The Keeper records the refused call as a step, with this text as its summary.
+
+Covered final parses: OpenAI Completions, Anthropic Messages, Bedrock Converse, Mistral,
+and the Responses shared implementation (Azure/Codex), including its second parse at
+`output_item.done`, which decides whether the call stays marked. Pi Messages receives
+arguments its upstream already finalized; Google adapters receive structured arguments.
+Neither has a final parse of its own to change. A reply cut off at the output limit
+(`length`) is refused by pi-agent-core itself, for all its tool calls.
+
+## Shared notes
+
+The assistant-message frame utility's checkpoint/replay/catch-up logic is separate
+from provider argument streaming and is unchanged. This patch does not promise a
+fixed latency bound for arbitrarily large single JSON values or transport bursts.
+Existing source maps still describe upstream code; line numbers after insertions shift.
+
+ProjectKeeper's runtime forwards `text_delta` only; it reads tool arguments at
+`tool_execution_start`, after finalization. It does not consume `toolcall_delta`
+argument snapshots. Public pi interfaces and session formats are unchanged.
+
+Local-only reproduction (no model keys or sessions):
+
+```sh
+node scripts/benchmark-tool-stream.ts --baseline
+node scripts/benchmark-tool-stream.ts
+node --test src/keeper/streaming-arguments.test.ts src/keeper/pi-streaming-patch.test.ts src/keeper/long-output-guards.test.ts src/qc/long-output.test.ts
+```
+
+The benchmark enters through coding-agent's `ModelRuntime`, the same provider-composition
+path as the Keeper service, with an in-memory empty credential store and a synthetic key.
+That unbundled SDK resolves its nested pi-ai installation; postinstall patches that copy
+and the root copy discovered in the lockfile. coding-agent's prebuilt CLI bundle is a
+different executable path and is not loaded by the ProjectKeeper service or changed here
+(so native pi, as opened by `Open in pi`, keeps upstream behaviour).
+The baseline command restores original pi-ai modules **in memory in its own process**;
+it does not change installed dependencies. The benchmark uses 20-character SSE deltas
+and a 10 ms heartbeat; reported latency is excess over that interval.
+The 200 KB baseline can take about ten seconds; the ordinary regression test uses
+100 KB and takes a fraction of a second when patched. It allows 1,500 ms heartbeat
+delay to leave ample margin for slower machines and the parallel full test suite.
+
+Investigated npm tarballs: 0.85.0, 0.85.1, 0.86.0, 0.86.1, 0.87.0, 0.87.1. All have the
+same `dist/utils/json-parse.js` SHA-256:
+`824fa2bf05b37d65b105ac8c07172d19f22f56a4ac66fbffba943933e4fb6d62`.
+Their provider delta sites still reparse accumulated arguments.
+The [0.86.0 changelog](https://github.com/earendil-works/pi/blob/v0.87.0/packages/ai/CHANGELOG.md)
+fix for quadratic `EventStream` draining addresses a different path. No upstream
+issue or pull request was submitted for this patch.