# 发布说明

## 当前状态

- npm 包名：`fmode-qiwei`
- 当前版本：`0.5.2`
- 状态：已发布到 npm，`latest=0.5.2`
- 运行要求：Node.js `22.5.0+`（使用内置 `node:sqlite`）
- Dashboard：`http://127.0.0.1:4320/`

## 上传前检查

```powershell
npm install
npm run release:check
npm pack --dry-run --json
```

`release:check` 会覆盖语法、MCP mock 网关、Agent 工作台、知识库、会议/文档/待办、目标管理、客户主档、客户旅程、输出规范、安装结构和实际 npm 包内容。
同时执行生产依赖审计；当前生产依赖漏洞数为 0。

## 安装方式

本地源码或解压包：

```powershell
node install.js workspace <客户项目目录> --smoke
```

本地 tgz：

```powershell
npm install -g .\fmode-qiwei-0.5.2.tgz
fmode-qiwei workspace <客户项目目录> --smoke
```

npm 发布后：

```powershell
npx --yes fmode-qiwei@latest workspace <客户项目目录> --smoke
```

workspace 安装会生成：

```text
<客户项目>/.claude/plugins/qiwei-assistant
<客户项目>/.claude/skills/<skill-name>/SKILL.md
<客户项目>/.mcp.json
<客户项目>/.gitignore
```

项目级 `.mcp.json` 使用安装目录内 `mcp/src/server.js` 的绝对路径，可从任意工作目录启动。
项目级 `.gitignore` 使用随 npm 包发布的模板幂等合并，保留客户已有规则并过滤本地凭据、运行状态和临时文件。

## 凭据与本地数据

- 优先级：MCP 请求参数 → 当前进程/Fmode Studio 环境 → 项目 `.env.local` → 用户级 Fmode/Claude Code 配置。
- 不把 token、设备 ID、客户 Session、数据库、日志或 Playwright 会话打入 npm 包。
- `.env.example` 只提供空占位符；Relay 默认关闭。
- 每个企微账号使用独立 Workbench 数据库和 Claude Code Session 映射。
- 旧版单账号 `agent-workbench.db` 会在首次启动时迁入当前账号独立库。

## 已知边界

- 白名单为空时拒绝启动真实监听。
- 企微订阅为 500 元/席位/月；本地开通页以服务端 `/subscribe/status` 返回价格为准，500 元仅作为状态读取异常时的回退值。
- Dashboard 可直接读取企微外部联系人并搜索、多选白名单；保存后写入客户项目 `.env.local` 并立即更新运行时安全边界。
- 私聊高置信自动回复仍受白名单和置信度阈值约束，低置信内容进入人工审核。
- 客户群默认使用人工审核；“无视风险 · 全自动”必须按群单独开启并二次确认，非空 Agent 回复会直接群发，模型或发送失败时停止并保留草稿。
- 官方会议 CLI 是否可用取决于企业微信向当前企业开放的机器人权限；不可用时页面会明确降级，不生成 Mock 会议。
- Fmode 登录/设备操作使用专用端点；业务消息通过 `/doApi`，不允许从通用转发口调用 `/client/*`。

## 发布命令

仅在版本、账号和仓库信息确认后执行：

```powershell
npm publish --access public
npm view fmode-qiwei name version dist-tags.latest --registry=https://registry.npmjs.org/
```

只有 `npm publish` 成功且 registry 查询验证通过后，才能将状态改为“已发布”。