@apolloyh/apollo-agent 0.1.9 → 0.1.11

package/docs/npm-release.md

@@ -0,0 +1,251 @@
+# Apollo npm 打包与发布手册
+
+本文说明如何把 `@apolloyh/apollo-agent` 构建为 npm tarball、发布到 npm，并把同一份 tarball 上传到 GitHub Release。
+
+## 前置条件
+
+- Node.js 20 或更高版本
+- npm 发布账号拥有 `@apolloyh/apollo-agent` 权限
+- npm 已登录：`npm whoami`
+- GitHub CLI 已登录：`gh auth status`
+- 工作目录为 Apollo 仓库的 `agent/`
+
+不要把 npm token、模型密钥、`.env` 或用户配置提交到仓库或放进安装包。
+
+## 1. 确定新版本号
+
+先查看 registry 当前版本：
+
+```bash
+npm view @apolloyh/apollo-agent version dist-tags.latest --json --prefer-online
+```
+
+npm 不允许覆盖已经发布的同名版本。按语义化版本选择升级类型：
+
+```bash
+npm version patch --no-git-tag-version  # 0.1.10 -> 0.1.11
+npm version minor --no-git-tag-version  # 0.1.10 -> 0.2.0
+npm version major --no-git-tag-version  # 0.1.10 -> 1.0.0
+```
+
+该命令会更新 `package.json` 和 `package-lock.json`。Apollo 还在 `src/brand.ts` 中显示版本号，必须同步修改：
+
+```ts
+export const PRODUCT = {
+  version: "0.1.11",
+  // ...
+};
+```
+
+确认三处一致：
+
+```bash
+node -p "require('./package.json').version"
+node -p "require('./package-lock.json').version"
+rg 'version:' src/brand.ts
+```
+
+## 2. 构建与验证
+
+```bash
+npm run typecheck
+npm test
+git diff --check
+git status --short
+```
+
+`npm test` 会先清理并重新生成 `dist/`，然后执行回归测试。发布前必须确认测试全部通过，并检查工作区没有混入无关修改或秘密。
+
+## 3. 打包 tarball
+
+Apollo 将历史安装包集中在 `releases/npm-packages/`。直接输出到该目录：
+
+```bash
+mkdir -p releases/npm-packages
+npm pack --json --pack-destination releases/npm-packages
+```
+
+`prepack` 会再次运行构建。生成文件形如：
+
+```text
+releases/npm-packages/apolloyh-apollo-agent-0.1.11.tgz
+```
+
+检查包内容：
+
+```bash
+tar -tzf releases/npm-packages/apolloyh-apollo-agent-0.1.11.tgz
+```
+
+重点确认包含：
+
+- `dist/`
+- `bundled-skills/`
+- `README.md`
+- `docs/`
+- `.apollo/config.example.json`
+- `.apollo/hooks.example.json`
+- `.env.example`
+
+同时确认不包含：
+
+- `.env`、API key、token
+- `node_modules/`
+- `.apollo/config.json`、sessions、memory、logs
+- 用户工作区的 `skills/`
+- 源码仓库中无关的大文件
+
+可先使用 `npm pack --dry-run` 只预览，不生成 tarball：
+
+```bash
+npm pack --dry-run
+```
+
+## 4. 本地安装冒烟测试
+
+在临时目录安装刚生成的真实 tarball：
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+TARBALL="releases/npm-packages/apolloyh-apollo-agent-${VERSION}.tgz"
+PREFIX=$(mktemp -d)
+
+npm install --prefix "$PREFIX" "$TARBALL" --ignore-scripts
+test -x "$PREFIX/node_modules/.bin/apollo"
+node --input-type=module -e "await import('$PREFIX/node_modules/@apolloyh/apollo-agent/dist/sdk.js'); console.log('SDK import ok')"
+rm -rf "$PREFIX"
+```
+
+## 5. 提交并推送源码
+
+发布前让 GitHub 的 `main` 与将要发布的代码一致：
+
+```bash
+git add package.json package-lock.json src/brand.ts README.md docs
+git commit -m "Release v$(node -p \"require('./package.json').version\")"
+git push origin main
+```
+
+不要使用 `git add -f skills/`。项目级 skills 属于用户工作区，不应跟踪或打进 npm 包；只有源码目录 `bundled-skills/` 属于产品内置资源。
+
+## 6. 发布到 npm
+
+Apollo 使用 npm 的浏览器 WebAuthn 流程，不需要 OTP：
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+TARBALL="releases/npm-packages/apolloyh-apollo-agent-${VERSION}.tgz"
+
+npx --yes npm@12.0.1 publish "$TARBALL" \
+  --access public \
+  --auth-type=web
+```
+
+终端显示 npm 官方授权地址后：
+
+1. 按 Enter 打开浏览器。
+2. 使用 Touch ID 或本机安全密钥确认。
+3. 保持终端运行，直到看到 `+ @apolloyh/apollo-agent@<version>`。
+
+不要复制浏览器授权链接到公开日志；该链接是临时登录流程的一部分。
+
+## 7. 验证 npm registry
+
+发布后 registry 可能需要数秒传播：
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+
+npm view "@apolloyh/apollo-agent@${VERSION}" \
+  version dist.shasum --json --prefer-online
+
+npm view @apolloyh/apollo-agent \
+  version dist-tags.latest --json --prefer-online
+```
+
+只有目标版本可查询且 `latest` 指向目标版本，才算 npm 发布完成。
+
+最后进行公开安装验证：
+
+```bash
+npm install -g @apolloyh/apollo-agent@latest --prefer-online
+apollo
+```
+
+## 8. 创建 GitHub Release
+
+把与 npm 发布完全相同的 tarball 作为 Release 附件：
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+TARBALL="releases/npm-packages/apolloyh-apollo-agent-${VERSION}.tgz"
+
+gh release create "v${VERSION}" "$TARBALL" \
+  --target main \
+  --title "Apollo v${VERSION}" \
+  --generate-notes
+```
+
+验证 Release 和附件：
+
+```bash
+gh release view "v${VERSION}" \
+  --json tagName,name,isDraft,isPrerelease,url,assets
+```
+
+如果 Release 已存在，只补传或替换附件：
+
+```bash
+gh release upload "v${VERSION}" "$TARBALL" --clobber
+```
+
+## 9. 完整发布清单
+
+- [ ] npm registry 上的旧版本已确认
+- [ ] `package.json`、`package-lock.json`、`src/brand.ts` 版本一致
+- [ ] 类型检查、构建和测试通过
+- [ ] tarball 内容正确且不含秘密
+- [ ] 真实 tarball 本地安装通过
+- [ ] 源码已提交并推送到 `main`
+- [ ] npm WebAuthn 发布成功
+- [ ] 目标版本可从 registry 查询
+- [ ] `latest` 指向目标版本
+- [ ] GitHub Release 已创建并附加同一 tarball
+- [ ] 工作区干净且本地分支与远端同步
+
+## 常见错误
+
+### `E403` 或版本已存在
+
+npm 版本不可覆盖。重新增加版本号、重新测试并打包，不要尝试覆盖旧版本。
+
+### `E404 Not Found`
+
+发布后短时间查询不到通常是 registry 传播延迟。等待几秒并使用 `--prefer-online` 重试。如果持续失败，再检查包权限和登录账号。
+
+### `EEXIST .../bin/apollo`
+
+本机已有旧的命令或手动软链接：
+
+```bash
+which apollo
+npm uninstall -g @apolloyh/apollo-agent
+```
+
+确认旧路径后再重新安装。不要直接使用 `--force`，除非已确认覆盖目标。
+
+### npm 要求 OTP
+
+本项目使用 WebAuthn 发布，应指定 `--auth-type=web`。按 Enter 打开 npm 官方授权页，然后使用 Touch ID 或安全密钥，不需要输入 OTP。
+
+### npm 发布成功但 GitHub Release 失败
+
+不要重新发布 npm。修复 GitHub 登录或网络问题后，重新执行 `gh release create` 或 `gh release upload` 即可。
+
+### 发布了有问题的版本
+
+已发布版本不能安全地原地替换。修复问题并发布新的 patch 版本。必要时可先标记旧版本：
+
+```bash
+npm deprecate @apolloyh/apollo-agent@0.1.11 "Please upgrade to a newer version."
+```

package/docs/sdk.md

@@ -10,14 +10,6 @@ Apollo SDK 用于把 Agent 能力嵌入 Node.js / TypeScript 系统。CLI 只是
 
 ## 安装
 
-当前使用本地 tarball：
-
-```bash
-npm install /Users/apollo/Code-YH/web-agent/agent/apolloyh-apollo-agent-0.1.3.tgz
-```
-
-发布到 npm 后可改为：
-
 ```bash
 npm install @apolloyh/apollo-agent
 ```
@@ -76,7 +68,7 @@ const engine = await createQueryEngine({
     authToken: tenant.modelApiKey,
     baseUrl: "https://open.bigmodel.cn/api/anthropic",
     model: "glm-5.2",
-    maxTokens: 4096,
+    maxTokens: 131_072,
     timeoutMs: 300_000,
     cacheTtl: "5m",
   },
@@ -196,7 +188,7 @@ const engine = await createQueryEngine({
 
 ## 会话恢复
 
-CLI 与 CC 一样支持 `apollo -c` 继续当前项目最近会话，以及 `apollo -r [session-id]` 选择或恢复指定会话。交互模式也可以使用 `/sessions` 和 `/resume [session-id]`。省略 ID 时可用 ↑/↓ 选择会话、Enter 恢复；恢复后终端会重新显示可读的历史对话。
+CLI 支持 `apollo -c` 继续当前项目最近会话，以及 `apollo -r [session-id]` 选择或恢复指定会话。交互模式也可以使用 `/sessions` 和 `/resume [session-id]`。省略 ID 时可用 ↑/↓ 选择会话、Enter 恢复；恢复后终端会重新显示可读的历史对话。
 
 ```ts
 const first = await createQueryEngine({ configPath, llmConfig });

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@apolloyh/apollo-agent",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "description": "Apollo — your personal agent. Answer first, act when needed, with tools, skills, and isolated Task subagents.",
   "bin": {
-    "apollo": "./dist/index.js"
+    "apollo": "dist/index.js"
   },
   "main": "./dist/sdk.js",
   "types": "./dist/sdk.d.ts",
@@ -22,8 +22,12 @@
     "dist",
     "bundled-skills",
     "README.md",
+    "docs/guide.md",
+    "docs/features-cc.md",
+    "docs/npm-release.md",
     "docs/sdk.md",
     ".apollo/config.example.json",
+    ".apollo/hooks.example.json",
     ".env.example"
   ],
   "publishConfig": {