# TextIn xParse for DeepSeek Harness

[English](README.md) | 简体中文

`@intsig-xparse/dsh-xparse` 会安装一个结构化的 `xparse` Tool、随包提供的
`xparse-parse` Skill，以及经过审核、供该 Tool 内部使用的 xparse CLI
二进制文件。

## 环境要求

- DeepSeek Harness `0.1.1-rc.2`
- Node.js 22.19 或更高版本，这是当前 Harness 依赖集的要求
- Linux 或 macOS，支持 x64/arm64；包内也包含 Windows 二进制文件，但目前的
  原生验证尚未覆盖 Windows

## 安装

```sh
dsh plugin --profile web add @intsig-xparse/dsh-xparse
dsh --profile web --dump-config
dsh --profile web
```

Tool 始终执行本包内嵌的二进制文件，不会使用 `PATH` 中的程序、全局安装的
`xparse-cli`、安装脚本或运行时下载。

## 支持的操作

首个版本开放以下操作：

- `parse`
- `quota`
- `get_doc_info`
- `get_outline`
- `search_text`
- `read_pages`
- `read_content`
- `task_run`
- `task_rerun`
- `task_status`
- `task_read`
- `task_export`
- `task_debug`
- `task_resume`

以下能力不对外开放：`get_confidence`、交互式 CLI 命令、任意 CLI 参数、自定义
请求头、自定义 Base URL、Task 密码、`task_continue`、前台 Task 等待控制、
`task_status.details` 和加密文档密码。提交或重新运行 Task 后，会立即返回
Task/Run 标识、状态、进度计数、终止状态和 `next_action`；后续进度查询应使用
精简且精确到 Run 的 `task_status` 响应。Task 调试和导出响应只会提供白名单内
的文件状态、错误码和恢复字段，不会暴露原始服务响应。

解析操作会将文档数据发送至 TextIn。文件上传和明确指定的付费解析遵循 Bundle
的 Harness 审批策略。Task 自动路由和重新运行不会仅仅因为后续可能需要付费
容量而提前请求批准：服务会先返回 `waiting_paid_authorization` 或
`waiting_funds`，只有随后针对确切 Run 执行 `task_resume` 时才会请求批准。
一次批准覆盖该次 Task Run，而不是每个文件分别批准；已获得授权的 Run 在充值后
通过 `after-funding` 重试时不会再次询问。解析结果会写入工作区产物，而不是将
完整长文档作为 Tool 文本返回。

## 凭据

浏览器中的 **设置 > 插件 > 插件配置 > TextIn xParse** 卡片会通过 Harness
的 `credentials.set` API 写入 App ID 和 Secret Code。Secret Code 不会进入
插件设置、Tool 参数或 Agent 对话。该卡片使用已配置的凭据引用，默认分别为
`XPARSE_APP_ID` 和 `XPARSE_SECRET_CODE`。

非敏感的 App ID 会同步到 `xparse` 设置命名空间，便于展示现有配置；Secret
Code 始终保持只写。已经配置凭据时，卡片会显示 App ID 和修改操作；尚未配置时，
AppKey 表单默认折叠，直到用户选择 AppKey 配置按钮。同一嵌套控件默认也会隐藏
已配置的 App ID 和修改操作。当 OAuth 已登录或存在完整 AppKey 时，外层 xParse
卡片默认折叠，否则默认展开。部署环境提供的环境变量具有更高优先级，并会使对应
控件变为只读。

同一卡片还支持 Device OAuth 登录：未登录时，Host 会自动启动内嵌 CLI 流程，
直接显示验证 URL 和用户代码，无需额外的登录按钮。可见登录 URL 包含
`launch_from=deepseek-harness`，OAuth 请求使用公开 Client ID
`plugin_deepseek_harness`。由其他 Client ID 创建的授权不会被复用；插件会启动
新的登录流程并替换旧授权。Host 会保存生成的 `xparse/oauth` 授权，并在使用前
进行刷新。Token 不会进入设置、浏览器、Tool 参数或对话文本。所有网络操作
（`parse`、`quota` 和 Task Runtime）都要求具备 OAuth 或完整 AppKey；已缓存的
本地导航操作仍可离线使用。

默认情况下，OAuth Access Token 会在过期前五分钟进入刷新窗口
（`oauthRefreshSkewMs: 300000`）。

当根 Agent 在没有可用凭据的情况下调用网络操作时，Tool 会启动 Device OAuth，
并在对话输入区打开专用的 xParse 登录卡片。卡片通过对齐的标题、授权区域和操作
区展示 xParse 标签、登录要求、验证链接、用户代码和完成操作；不会暴露通用问题
表单、跳过或提交控件。授权成功后，卡片会关闭，授权信息会保存在 Host 端，随后
继续原始 Tool 调用。用户也可以在卡片中确认完成或取消登录。登录等待发生在 CLI
执行超时开始计时之前。

子 Agent、无界面调用方以及没有问题提供器的部署环境必须改用插件设置卡片完成
登录。

切勿在对话或 Tool 调用中粘贴 App ID、Secret Code、OAuth Token 或文档密码。

## 状态与产物

适配器通过 `XPARSE_STATE_DIR` 为每个会话分配
`<workspace>/.xparse/sessions/` 下的状态目录。解析产物使用
`<workspace>/.xparse/calls/` 下的独立调用目录。文件访问权限仍以沙箱策略为准。
每个内嵌 CLI 子进程还会收到 `XPARSE_CLIENT_FROM=deepseek-harness`，因此
TextIn API 请求会携带 `X-From: deepseek-harness`，而不是独立 CLI 使用的
`cli` 来源标识。

## 来源追踪

`embedded-cli-manifest.json` 记录每个内嵌二进制文件的源码版本、协议版本、路径
和 SHA-256 摘要。`skill-source.json` 记录外部 Skill 仓库、锁定提交、MIT
许可证和文件摘要。

## 开发

本仓库仅负责 DeepSeek Harness 插件。内嵌 CLI 由 `xparse-client` 构建，通用
Skill 由 `xparse-skills` 维护；经过审核的版本固定在 `release-lock.json` 中，
并且只在组装阶段生成到本仓库。

安装依赖并运行源码级检查：

```sh
npm install
npm run typecheck
npm test
npm run build
```

生成的发布输入不会提交到仓库。CLI 二进制文件来自六个 npm 平台包；每个包的
URL、npm integrity、tarball SHA-256 和二进制 SHA-256 都固定在
`release-lock.json` 中。填充或验证缓存：

```sh
npm run fetch:cli
npm run fetch:skill
```

然后使用锁定 Skill 的干净检出版本进行组装：

```sh
python3 scripts/prepare-dsh-xparse.py \
  --skill-dir /path/to/xparse-skills/skills/xparse-parse
```

使用 `--offline` 可以在不访问注册表的情况下，通过已验证缓存证明组装过程可复现。

组装完成后，验证软件包并实际启动 DSH Web：

```sh
npm run validate:docker
```

## 发布

使用一条命令构建完整的 npm tarball 和校验清单：

```sh
npm run release:build -- --output-dir dist/release
```

该命令会获取锁定的 Skill 和 CLI 产物、组装生成内容、编译 TypeScript、执行
`npm pack`、验证 tarball，并写入 `SHA256SUMS`。添加 `--offline` 可以强制要求
两类输入均来自已验证缓存。

GitHub CI 会在每个 Pull Request 上执行相同的发布构建，并上传供审核的产物。
推送 `v<package-version>` 标签会触发发布工作流，将经过验证的同一 tarball 发布
到 npm，并把 tarball 和校验文件附加到 GitHub Release。创建发布标签前，需要为
仓库 Secret `NPM_TOKEN` 配置 `@intsig-xparse/dsh-xparse` 的发布权限。