git:20261019.ae1118d to git:20261019.f7f08e1

# AGENTS.md

本仓库是 **本地网关 + 逆向研究** 项目：不提供任何对外运行时能力，只服务本机、本账号。

当前实现为 **TypeScript**（Node ≥ 22.6），是 `modelmux` 工作区的一个渠道包。

## 不可协商的约束

- **凭据零入库、零回显**：不得把任何真实 token / 机器码 / 密钥写进代码、文档、

日志或 commit。对外输出只允许脱敏形态（`前缀…[长度]`）与 sha256 指纹。

- **只读为本**：所有研究脚本默认不得写入妙手的安装目录与 userData 目录；

唯一允许的写操作是仓库自己的目录与 `~/.modelmux/catpaw/`。

- **唯一出网口**：`catpaw` CLI 与网关按设计访问上游；新增任何出网代码前先问用户。

- **证据等级不可省**：任何结论必须带 `[实测]` / `[代码]` / `[推断]` / `[参考]` 标记

- **算法结论以代码为准**：不得靠长度/熵"猜"算法；必须给出 `app.asar` 里的实现片段。

## 机制约束

- TypeScript ≥ 5.9，严格模式，Node ≥ 22.6；零第三方运行依赖。

- `src/` 只有 7 个文件（`channel.ts` / `cli.ts` / `index.ts` / `cred.ts` /

`upstream.ts` / `catalog.ts` / `billing.ts`），其余一律复用 `@modelmux/gateway`。

- 文本文件一律 **LF**（`.gitattributes` 已锁定）。

- 文档与代码同 commit 更新：改了阶段实现就要改对应文档。

## 改动前的检查

```bash

npm run build # 编译到 dist/（tsc 严格模式）

npm run typecheck # 类型检查

```

→ 渠道不写测试（`AGENTS.md` 的「测试规则」第 1 条）：无 `tests/selftest.test.ts`，无 `scripts.test`。

全仓验证（在工作区根）：

```bash

npm run build && npm run test --workspaces --if-present

```

涉及登录链路、上游协议翻译的改动，必须额外跑一次真实机器验证：

`mx login catpaw` → `mx status catpaw` → 一次真实流式 chat。