dsh-scout 0.8.0

package/docs/dsh-scout-product-contract.md

@@ -0,0 +1,108 @@
+# dsh-scout 产品契约
+
+状态：Draft 0.1
+目标：把公司与岗位尽调收敛为一个可复现、可追溯、能支持下一步行动的 DSH 场景插件。
+
+当前实现进度：首个公开切片已经覆盖 session 隔离的内存 case、封闭来源类型、主体核验、claim 证据历史、保守三态决策、结构化报告、卸载清理和临时 DSH profile 安装门禁；v0.2 已落地持久化五文件导出（`scout_export` / `scout_import`，含可回放事件流 `events.jsonl` 与导入后决策重算）；v0.3 已落地可配置存储（`scoutDir` / `autoPersist` 插件配置）与面试问题生成（`scout_questions`）；v0.4 已落地信息采集登记（`scout_ingest`：批量登记采集结果并按 URL 自动推断来源类型与证据等级）；v0.5 已落地公司/岗位对比（`scout_compare`：2–5 案例并排对比报告与合并面试问题）；v0.6 已落地采集→主张流转（`scout_ingest` 支持 claim 草稿，登记来源同时自动添加主张）；v0.7 已落地 Provider 深度集成（`scout_search`：接入 DSH Web Provider，搜索结果自动登记为来源）。
+
+## 1. 产品承诺
+
+给定一个公司和一个岗位，`dsh-scout` 不承诺“找到所有信息”，而承诺在证据边界内回答：
+
+> 这个机会是否值得进入下一轮？如果值得，面试中必须验证什么？
+
+所有重要结论必须绑定来源、证据等级和下一步动作；无法验证的内容必须保留为 `unknown` 或 `needs_verification`，不能被润色成事实。
+
+## 2. 首个用户流程
+
+输入：
+
+- 公司名称或官网
+- 岗位名称或岗位链接
+- 用户目标（默认：是否值得进入下一轮）
+
+流程：
+
+1. 确认公司主体：名称、注册主体、品牌名和地域；存在歧义时暂停。
+2. 建立九段式调查卡：公司与创始人、产品与技术、市场与竞争、融资与商业化、组织与 HR、风险、岗位匹配、面试反问、待核验事项。
+3. 采集并归档来源；保存抓取时间、来源类型和原始链接。
+4. 将事实、推断、用户提供信息和未知项分开。
+5. 生成三态判断：`PROCEED`、`VERIFY` 或 `STOP`。
+6. 输出报告、证据清单、风险清单和面试问题。
+
+## 3. 首版输出物
+
+每个 case 生成一个可复制的目录：
+
+```text
+scout-cases/<case-id>/
+  case.json
+  sources.json
+  claims.json
+  events.jsonl
+  report.md
+```
+
+首版不要求精确的总分。报告必须包含：
+
+- 一句话判断和判断状态
+- 3 个支持判断的关键证据
+- 3 个阻断或待核验风险
+- 岗位可能的真实任务与权限假设
+- 5-10 个面试反问
+- 下一步最小核验动作
+
+## 4. 证据模型
+
+证据等级是来源质量标签，不是事实真伪的自动证明：
+
+| 等级 | 含义 |
+| --- | --- |
+| `E0` | 未找到证据或仅为模型猜测 |
+| `E1` | 用户提供、招聘信息或公司自述 |
+| `E2` | 独立媒体、公开数据库或多源交叉信息 |
+| `E3` | 工商、监管、官方文件或可直接复核的一手资料 |
+
+每条 claim 至少包含：`claim_id`、`text`、`status`、`evidence_level`、`source_ids`、`confidence_note` 和 `next_action`。
+
+允许的 `status`：`verified`、`reported`、`inferred`、`contradicted`、`unknown`、`needs_verification`。
+
+## 5. DSH 插件边界
+
+首版作为外部 bundle，优先使用现有工具、子 Agent、任务和文件系统能力：
+
+- 工具：启动 case、核验 claim、比较公司、生成面试问题、导出报告。
+- 事件观察：记录工具结果和来源归档，不重写 Agent Loop。
+- 配置：来源目录、报告目录、并发数、超时和输出语言必须是可配置字段。
+- 生命周期：所有 watcher、后台任务、连接和临时文件都必须在卸载时清理。
+
+首版不新增模型可见的持久化事件；如果未来需要让 case 状态进入模型上下文，必须为其设计可回放的 session event。
+
+## 6. 明确非目标
+
+- 不重做通用搜索、浏览器或 MCP provider。
+- 不自动发送求职邮件、提交申请或联系第三方。
+- 不把公司融资、估值、专利数量或招聘规模直接转化为成功判断。
+- 不把个人简历、身份信息或求职意图默认发送给第三方服务。
+- 不提供法律、投资或医疗结论。
+- 不在首版实现完整 Web UI、实时数据库或公司评分排行榜。
+
+## 7. 首个验收案例
+
+使用 `docs/fixtures/dsh-scout/snapmaker-hr-head.json` 作为离线 fixture，验证：
+
+1. 公司主体存在未确认时，case 不能直接进入 `PROCEED`。
+2. 用户历史材料可以作为 `E1/reported`，不能冒充当前独立事实。
+3. 至少一个 claim 能从 `needs_verification` 转为 `verified`，并保留来源变化。
+4. 报告能生成面试问题，而不是只输出摘要。
+5. 没有来源的高影响结论必须显示为未知或待核验。
+
+## 8. 成功标准
+
+首个 MVP 通过的条件：
+
+- 一个真实 case 可以从输入运行到报告导出。
+- 每个高影响结论都能追溯到 claim 和 source。
+- 同一 fixture 在无网络模式下可重放并得到结构稳定的结果。
+- 失败时输出缺失证据和下一步动作，而不是编造补全。
+- 插件可以加载、卸载、重载，不遗留 watcher、任务或连接。

package/docs/fixtures/dsh-scout/snapmaker-hr-head.json

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": "dsh-scout.case.v0",
+  "caseId": "snapmaker-hr-head",
+  "title": "Snapmaker HR Head opportunity",
+  "language": "zh-CN",
+  "decisionObjective": "判断是否值得进入下一轮，并准备面试反问",
+  "subject": {
+    "name": "Snapmaker",
+    "possibleLegalEntity": "深圳快造科技有限公司",
+    "identitySourceIds": [],
+    "identityStatus": "needs_verification",
+    "identityNote": "这是历史调研案例标识，不是当前工商核验结果。运行时必须重新确认主体。"
+  },
+  "role": {
+    "title": "HR Head / HR 负责人",
+    "location": "深圳",
+    "fitQuestion": "该岗位是否拥有足够的业务授权，值得以 HR 一号位方向继续推进？"
+  },
+  "expectedDecision": "VERIFY",
+  "expectedDecisionReason": "历史材料显示岗位匹配度较高，但公司主体、当前组织规模、授权边界和真实业务优先级必须现场核验。",
+  "dimensions": [
+    "company_and_founder",
+    "product_and_technology",
+    "market_and_competition",
+    "financing_and_commercialization",
+    "organization_and_hr",
+    "risks",
+    "role_fit",
+    "interview_questions",
+    "next_verifications"
+  ],
+  "sources": [
+    {
+      "sourceId": "historical-snapmaker-research",
+      "type": "user_provided_historical_report",
+      "title": "Max 既有 Snapmaker 深度调研与面试复盘",
+      "url": null,
+      "capturedAt": null,
+      "evidenceLevel": "E1",
+      "status": "historical_only",
+      "note": "用于离线 fixture 的方法验证；不能替代运行时实时来源。"
+    }
+  ],
+  "claims": [
+    {
+      "claimId": "claim-identity",
+      "text": "品牌名 Snapmaker 与候选注册主体需要在运行时确认是否对应。",
+      "status": "needs_verification",
+      "evidenceLevel": "E0",
+      "dimension": "identity",
+      "impact": "blocking",
+      "sourceIds": [],
+      "confidenceNote": "历史案例只提供候选主体名称，没有当前工商核验来源。",
+      "nextAction": "查询工商主体、法定代表人、注册地和品牌关联信息。"
+    },
+    {
+      "claimId": "claim-role-scope",
+      "text": "该岗位可能承担从 0 到 1 搭建 HR 体系的职责。",
+      "status": "reported",
+      "evidenceLevel": "E1",
+      "dimension": "mandate",
+      "impact": "blocking",
+      "sourceIds": ["historical-snapmaker-research"],
+      "confidenceNote": "该判断来自历史调研材料，不能代表岗位当前授权。",
+      "nextAction": "面试确认汇报对象、团队现状、预算权限和前三个必须交付的业务结果。"
+    },
+    {
+      "claimId": "claim-fit",
+      "text": "Max 的 HRBP、SAP 变革、AI 硬件和 AI Agent 经验与该岗位可能存在较高匹配。",
+      "status": "inferred",
+      "evidenceLevel": "E1",
+      "dimension": "role_fit",
+      "impact": "material",
+      "sourceIds": ["historical-snapmaker-research"],
+      "confidenceNote": "匹配度是基于历史岗位假设的本地推断，尚未由当前招聘方确认。",
+      "nextAction": "用岗位真实授权边界和 CEO 对 HR 的期待验证匹配，而不是只比较年限。"
+    }
+  ],
+  "interviewQuestions": [
+    "如果 HR 只能在前三个月完成一件事，您希望它是什么？",
+    "这个岗位拥有的是执行权、建议权，还是组织变革的共同决策权？",
+    "当前最影响业务增长的组织问题是什么？它为什么现在才需要解决？",
+    "CEO 对 HR 的期待中，哪些是明确目标，哪些只是临时救火？",
+    "这个岗位在 6 个月后被认为成功，具体会看到哪些结果？"
+  ],
+  "openQuestions": [
+    "当前公司主体和品牌关系是否已核验？",
+    "岗位是否真实存在，汇报关系和团队规模是否与历史信息一致？",
+    "HR 是业务战略角色，还是行政与招聘补位角色？",
+    "岗位的预算、团队和决策权限是否足以完成目标？"
+  ]
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "dsh-scout",
+  "version": "0.8.0",
+  "description": "Evidence-driven company and job intelligence plugin for DeepSeek Harness.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "cordis.patch.yml",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "tests",
+    "README.en.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "check": "npm test",
+    "test:profile": "node scripts/profile-smoke.mjs",
+    "check:release": "npm test && npm run test:profile && pnpm pack --dry-run",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.1 <5",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6 <0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "typescript": "^5.8.3"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaxHou-infinity/dsh-scout.git"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "company-research",
+    "job-intelligence",
+    "hrbp"
+  ]
+}

package/scripts/profile-smoke.mjs

@@ -0,0 +1,101 @@
+import assert from 'node:assert/strict'
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const DSH_VERSION = '0.1.0-rc.6'
+const command = name => process.platform === 'win32' ? `${name}.cmd` : name
+const localDsh = join(process.cwd(), 'node_modules', '.bin', command('dsh'))
+const dshCommand = process.env.DSH_BIN
+  ? { program: process.env.DSH_BIN, prefix: [] }
+  : existsSync(localDsh)
+    ? { program: localDsh, prefix: [] }
+    : { program: 'npx', prefix: ['--yes', `@deepseek-ai/dsh@${DSH_VERSION}`] }
+
+function run(program, args, options = {}) {
+  const result = spawnSync(command(program), args, {
+    cwd: process.cwd(),
+    env: options.env ?? process.env,
+    encoding: 'utf8',
+    stdio: options.capture ? 'pipe' : 'inherit',
+  })
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    const details = [result.stdout, result.stderr].filter(Boolean).join('\n').trim()
+    throw new Error([
+      `${program} ${args.join(' ')} failed with exit code ${result.status}`,
+      details,
+    ].filter(Boolean).join('\n'))
+  }
+  return result.stdout ?? ''
+}
+
+const packageJson = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'))
+const gateRoot = await mkdtemp(join(tmpdir(), 'dsh-scout-profile-gate-'))
+const dshHome = join(gateRoot, 'home')
+const tarball = join(gateRoot, `${packageJson.name}-${packageJson.version}.tgz`)
+const verifierPath = join(gateRoot, 'verify-lifecycle.mjs')
+const patchPath = join(gateRoot, 'verify-lifecycle.patch.yml')
+const gateEnv = {
+  ...process.env,
+  DSH_HOME: dshHome,
+  DSH_TELEMETRY_MODE: 'DISABLED',
+}
+
+try {
+  await writeFile(verifierPath, `
+export const inject = ['tools']
+export async function apply(ctx) {
+  await new Promise(resolve => setTimeout(resolve, 25))
+  const required = ${JSON.stringify([
+    'scout_start',
+    'scout_add_source',
+    'scout_add_claim',
+    'scout_verify_identity',
+    'scout_verify_claim',
+    'scout_report',
+  ])}
+  for (const name of required) {
+    if (!ctx.tools.get(name)) throw new Error(\`missing dsh-scout tool: \${name}\`)
+  }
+  if (typeof ctx.appExit !== 'function') throw new Error('missing launcher appExit service')
+  process.stdout.write('DSH_SCOUT_LOAD\\n')
+  ctx.effect(() => () => process.stdout.write('DSH_SCOUT_UNLOAD\\n'))
+  queueMicrotask(() => ctx.appExit(0))
+}
+`)
+  await writeFile(patchPath, `- insert:\n    - id: dsh-scout-smoke-verifier\n      name: ${JSON.stringify(verifierPath)}\n`)
+  run('pnpm', ['pack', '--pack-destination', gateRoot])
+  run(dshCommand.program, [
+    ...dshCommand.prefix,
+    'plugin',
+    '--profile',
+    'scout-smoke',
+    'add',
+    `file:${tarball}`,
+  ], { env: gateEnv })
+  const config = run(dshCommand.program, [
+    ...dshCommand.prefix,
+    '--profile',
+    'scout-smoke',
+    '--dump-config',
+  ], {
+    capture: true,
+    env: gateEnv,
+  })
+  assert.match(config, /# == dsh-scout\n- id: dsh-scout\n  name: dsh-scout/)
+  const lifecycle = run(dshCommand.program, [
+    ...dshCommand.prefix,
+    '--profile',
+    'scout-smoke',
+    '--patch',
+    patchPath,
+  ], { capture: true, env: gateEnv })
+  assert.match(lifecycle, /DSH_SCOUT_LOAD/)
+  assert.match(lifecycle, /DSH_SCOUT_UNLOAD/)
+  console.log('dsh-scout profile smoke: PASS')
+} finally {
+  await rm(gateRoot, { recursive: true, force: true })
+}