intsig-textin/dsh-plugin-xparse

面向 DeepSeek Harness 的 TextIn xParse

@intsig-xparse/dsh-xparse 安装一个结构化的 xparse Tool、捆绑的
xparse-parse Skill，以及该 Tool 内部使用的、经过审查的 xparse CLI 二进制文件。

要求

- DeepSeek Harness 0.1.1-rc.2
- Node.js 22.19 或更高版本，这是当前 Harness 依赖集所要求的
- x64/arm64 上的 Linux 或 macOS；Windows 二进制文件已打包，但不属于
当前原生验证证据的一部分

安装

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 参数、自定义
请求头、自定义基础 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，并且仅针对
确切的后续 task_resume 操作请求批准。一次批准
覆盖该 Task Run，而非每个文件一次批准；对已授权 Run 的
after-funding 重试不会再次询问。结果会作为工作区
产物写入，而不是将完整的长文档作为 Tool 文本返回。

凭据

Settings > Plugins > Plugin configuration > 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
和 Modify 操作，而未配置的卡片会保持 AppKey 表单折叠，直到用户选择 AppKey 配置
按钮。同一嵌套控件会隐藏已配置的 App ID 和修改
默认情况下执行操作。当 OAuth 已登录或存在完整的 AppKey 时，外层 xParse 卡片启动时处于折叠状态；否则启动时展开。部署提供的环境值保持更高优先级，并使相应控件变为只读。同一张卡片提供设备 OAuth 登录：在登出状态下，Host 会自动启动嵌入式 CLI 流程，并直接显示验证 URL/代码，无需单独的登录按钮。可见的登录 URL 包含 launch_from=deepseek-harness，OAuth 请求使用公共 Client ID plugin_deepseek_harness。为其他 Client ID 创建的授权不会被复用；插件会启动新的登录并替换它们。Host 存储生成的 xparse/oauth 授权，并在使用前刷新它。令牌永远不会到达设置、浏览器、Tool 参数或对话文本。每个网络操作（parse、quota 和 Task Runtime）都需要 OAuth 或完整的 AppKey；缓存的本地导航仍可离线使用。

OAuth 访问令牌默认在到期前五分钟进入刷新窗口（oauthRefreshSkewMs: 300000）。

当根 Agent 在没有可用凭据的情况下调用网络操作时，Tool 会启动设备 OAuth，并在对话编辑器中打开专用的 xParse 登录卡片。该卡片使用对齐的页眉、授权面板和操作页脚，用于显示 xParse 标签、登录要求、验证链接、用户代码和完成控件；它不会暴露通用问题表单、跳过或提交控件。授权成功后会关闭卡片，在 Host 侧存储授权，并继续原始 Tool 调用。用户也可以从卡片确认完成或取消。登录等待发生在 CLI 执行截止时间之前。子代理、无头调用方以及没有问题提供程序的部署必须改用插件设置卡片。

切勿将 App ID、Secret Code、OAuth 令牌或文档密码粘贴到对话或 Tool 调用中。

状态与产物

适配器通过 XPARSE_STATE_DIR 在 /.xparse/sessions/ 下分配一个会话作用域的状态目录。解析产物使用 /.xparse/calls/ 下的每次调用目录。沙箱仍然是文件访问的权威。每个嵌入式 CLI 子进程还会收到 XPARSE_CLIENT_FROM=deepseek-harness，因此 TextIn API 请求携带 X-From: deepseek-harness，而不是独立的 cli 归属信息。

来源

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

开发

此仓库仅拥有 DeepSeek Harness 插件。嵌入式 CLI 由 xparse-client 构建，通用 Skill 由 xparse-skills 维护；已审查的修订版本固定在 release-lock.json 中，并且仅在组装期间物化。
安装依赖并运行源码级检查：

npm install
npm run typecheck
npm test
npm run build

生成的发布输入有意不提交。CLI 二进制文件从六个 npm 平台包 tarball 下载，这些 tarball 通过 release-lock.json 中的 URL、npm 完整性校验、tarball SHA-256 和二进制文件 SHA-256 进行固定。使用以下命令填充或验证缓存：

npm run fetch:cli
npm run fetch:skill

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

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

使用 --offline 来证明组装过程可以从已验证的缓存中复现，而无需访问注册表。

组装完成后，使用以下命令验证包和真实的 DSH Web 启动：

npm run validate:docker

发布

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

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

该命令会获取锁定的 Skill 和 CLI 构件，组装生成的输入，编译 TypeScript，运行 npm pack，验证 tarball，并写入 SHA256SUMS。添加 --offline 以要求两个缓存均已验证。

GitHub CI 会在每个拉取请求上执行相同的发布构建，并上传审查构件。推送标签 v 会运行发布工作流，将经过验证的确切 tarball 发布到 npm，并将 tarball 及校验和附加到 GitHub Release。在创建发布标签之前，请配置仓库密钥 NPM_TOKEN，使其具有对 @intsig-xparse/dsh-xparse 的发布访问权限。