内容
sii (TypeScript)
[](LICENSE)
[](package.json)
用于自动与智利税务局（SII）交互的TypeScript核心库 + 命令行界面（CLI）+ MCP服务器，适用于用户在其自己的RUT下以及其授权代表的公司中使用。设计用于在 **Claude Code** 和 **Claude Desktop** 中使用。
从`sii-cli`（Python）重写为TypeScript：继承了SII知识和限制；代码全新编写。
> ⚠️ **非官方工具。** 本项目 **不隶属于SII，也不得到SII支持**。按照“原样”提供（参见 [LICENSE](LICENSE)），不提供任何类型的保证。每个用户负责遵守SII的服务条款和智利法律。自动与公共机构的门户交互：请谨慎使用（账户在登录尝试失败后将被锁定；锁定后请勿重试）。
## 状态
**读取** 接口已上线并实时身份验证（`auth`）、代理（`operate`）、**RCV**、**F22** （状态/表格/观察/历史）、**F29** （第一阶段）、**BTE/BHE**、**授权DTE** （公共查询）、**whoami** 和 **行政请求** （SISPAD）。第一个 **写入** 接口：`bte emit` （电子账单发行）。详见 [`docs/CURRENT_STATUS.md`](docs/CURRENT_STATUS.md) 和 [`docs/ROADMAP.md`](docs/ROADMAP.md)。
## 结构
```text/
core/albertomarturelo/sii-core 域核心（）。接口仅调用其任务。
cli/ @albertomarturelo/sii-cli 人机（终端）。Claude通过Bash运行。
/ @albertomarturelo/sii MCP服务器（stdio）。Claude Code和Claude Desktop的集成点。
docs/上下文层（架构、约定、ADR...）。
```
单个`@albertomarturelo/sii-core`）支持两个接口，因此所有法律和操作限制（速率限制、凭证管理、operate中心）都适用，无论接口如何。外部依赖（门户、机密、会话、审计、时钟）位于可注入的缝隙中，以便测试不会触及实际的SII。参见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
## 如何与Claude一起使用
- **Claude Desktop** — 通过 `claude_desktop_config.json` 连接MCP服务器（`sii-mcp`，stdio）。
- **Claude Code** — 连接同一个MCP（`.mcp.json` / `claude mcp add`），和/或让Claude Code直接通过Bash使用命令行界面。
税务密钥（Clave Tributaria）从未以明文形式存储M或磁盘上：登录（仅cookie）- 任何MCP工具都不会接收密码。参见 [ADR](docs/decisions/006-auth-posture-browser-cookies-host-secrets.md)。
## 安装和使用
要 **使用** （无需克隆仓库）。需要 **Node ≥ 20**。有关开发，请参见 [开发](#开发)。
```bash
# 1) 安装命令行界面和MCP服务器
npm i -g @albertomarturelo/sii-cli @albertomarturelo/sii-mcp
# 2) 安装用于登录的浏览器（仅一次，约100-150 MB）
npx playwright install chromium
# 3) 登录 - 在SII真实页面打开浏览器；输入您的RUT + 密钥。
# 密钥从未到达模型或磁盘。
sii auth login
# 4) 从终端使用
sii peticiones list # 我有哪些待处理的行政请求（“等待文件”）？
sii rcv summary 2026-05 # 2026-05月的采购RCV摘要
sii f29 overview 2026 # 2026年每月增值税状况
```
### 将MCP连接到Claude
服务器是 **stdio** （无需托管）：Claude将其作为进程启动。
**Claude Desktop** - 添加到 `claude_desktop_config.json` 并重启应用程序
（macOS：`~/Library/Application Support/Claude/`；Windows：`%APPDATA%\Claude\`）：
```json
{
"mcpServers": {
"sii": { "command": "sii-mcp" }
}
}
```
aude Code** -：
```bash
claude mcp add sii -- sii-mcp
```
然后语言请求（例如“状态是什么？”或“6-05月的采购RCV”）。如果您，请先运行 `sii auth login` （或请求Claude的 `auth_login` 工具，它会打开您的浏览器工具不会更改任何内容；发出BHE需要显。
> **Play 是唯一一个重要的依赖`sii` 使用它进行基于浏览器的登录（仅限cookie，ADR-006）。因此，第二个步骤（px playwright install chromium`）是必需的；npm包不会自动下载浏览器。
## 功能
两个接口都公开了对SII的相同操作（单个核心）：**MCP** 将其作为工具提供给Claude；**命令行界面** 作为 `sii …` 命令。
### 通过MCP（Claude Desktop / Claude Code）
Claude将操作视为具有可配置权限的工具（读取与写入）。**写入** 操作 - 登录/注销、操作和 **发出** BHE - 是受控的：`bte_emit` 是destructive` 操作式确认。
**提示示例** （自然语言；Claude选择工具）：
- “我的会话状态是什么，我以哪个RUT的名义操作？”→ `auth_status`
- “显示2026-05月的 **采购** RCV摘要。”→ `rcv_summary`
- “列出2026-05月的RC详情。”→ `rc- “我的202所得税申报（F怎么样了？”→22_status` / `_formulario`
- “5年F22观察结果吗？”→22_observaciones “2026年我的F29）每月状况→ `f29`
- “给我2025月的F29提案，按行分组。”→ `f29_formulario`
- “哪个RUT有权发行DTE 77.777.777-7？”→ `dte_authorized` （公共，无需登录）
- “列出2026年6月我 **收到** 的荣誉账单。”→ `bte_list`
- “我有任何在SII前台被阻止的行政请求吗？”→ `peticiones_list`
- “我注册的姓名和电子邮件是多少？”→ `whoami`
- “模拟一张价值$500,000的荣誉账单（未发出）。”→ `bte_emit_preview`
- “切换到我代表的公司。”→ `operate`
> 发出真正的BHE（`bte_emit`）**不会** 通过单独的提示进行：它是一种 `destructive` 工具，需要显式确认 + 回声中的金额（ADR-017）。登录会打开您的浏览器到SII的真实页面 - 密钥从未到达模型。
### 通过命令行界面（`sii`）
默认 **JSON输出** （可通过 `jq` 管道传输）；`--human适用于人类阅读。`operando como …` 头部信息输出到STDERR。
| 命令 | 功能 |
|---|---|
| `sii auth login [--console]` | 登录（基于浏览器的cookie-only；`--console` 通过终端请求密钥） |
| `sii auth status [--refresh]` | 我是谁 / 我以哪个RUT的名义操作（`--refresh` 从门户读取） |
| `sii auth logout` | 注销（服务器最佳努力关闭 + 本地清理） |
| `sii operate <rut> \| --self \| --list` | 选择要操作的RUT / 列出可操作集 |
| `sii rcv summary <periodo>` | 采购和销售登记（RCV）摘要 |
| `sii rcv list <periodo> [--compra\|--venta] [--rut]` | RCV文档详情 |
| `sii f22 status [año]` | 年度所得税申报（F22）状态；无年份 → 多年期概览 |
| `sii f22 formulario <año>` | 完整的F22表格，分类（收入/扣除/扣缴/结果） |
| `sii f22 observaciones <año> [--folio]` | F22观察/不一致 |
| `sii f22 historial <año> [--folio]` | F22事件时间线（退税，转账，修正） |
| `sii f29 formulario <periodo>` | 带标签和分类的增值税（F29）提案 |
| `sii f29 overview <desde> <hasta> \| <año>` | 增值税每月状况，某段时间内 |
| `sii f29 status <periodo>` | 某个月的F29状态 |
| `sii bte list <periodo> [--recibidas\|--emitidas]` | 荣誉账单，某个月 |
| `sii bte emit …` (`--confirm <monto>`) | 发出电子荣誉账单 - 默认预览；实际发行需要 `--confirm` |
| `sii dte authorized <rut>` | 公共查询：某个RUT可以发行的DTE |
| `sii peticiones list [--rut]` | 行政请求（SISPAD）+ 其状态时间线 |
| `sii whoami` | 身份验证账户的公司名称/邮箱 + 邮箱 |
**会话密钥** 接口（`f22`、`f29`、`bte始终读取主会话 `--rut`）；RUT** 接口（`rcv`）接受 `--rut` / `operate` 以访问代表的公司（ADR-005）。
## 身份模型
每次一个活动账户（切换账户 = `logout` → `login在会话中，一个 ** 账户使用指针` 选择以哪个的名义操作（默认为代表的公司）。**公司** 账户不代表。参见 [005](docs/decisions-single-account-operate-centric-identity.md)。
##```bash
pnpm install # 安装依赖
pnpm build # tsc -b（类型检查 + 构建所有包）
pnpm test # vitest
pnpm lint # eslint
pnpm format # prettier
```
需要Node `>=20` 和 `packageManager` 中固定的pnpm（`package.json`）。
## 方法论
仓库采用 **Context-First Development（CFD）**：代码之前的决策（ADR），每个会话首先读取的上下文层，以及 `.claude/commands/`杠命令（`/session:start`，`/session，`/decision:new`，`/issue:new`，`/issue:start`，`/review-pr`，`/context:validate`）。参见 [ADR-001](docs/decisions/001-adopt-cfd-methodology.md)。
## 安全
请勿上传真实的机密或个人身份信息（RUT、密钥、cookie、姓名、金额）。要报告漏洞和查看安全立场，请阅读 [`SECURITY.md`](SECURITY.md)。
## 贡献
欢迎贡献 - 从 [`CONTRIBUTING.md`](CONTRIBUTING.md) 和 [`docs/`](docs/) 中的上下文层开始。
## 许可证
[MIT](LICENSE) © 2026 Alberto Marturelo Lorenzo. 参见 [ADR-018](docs/decisions/018-public-release-mit-license.md)。
