dsh-industry-research 0.1.0

package/README.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# 🏭 dsh-industry-research
+
+**Industry and company research domain pack for DeepSeek Harness.**
+
+*Chain maps, public-source tracking, company cards, and auditable reports — every number traces to a source, every gap is declared.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-industry-research/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-industry-research/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-industry-research?label=version)](https://github.com/PerryLink/dsh-industry-research/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-industry-research)](https://www.npmjs.com/package/dsh-industry-research)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-industry-research)](https://www.npmjs.com/package/dsh-industry-research)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+**仅供研究，不构成投资建议 — Research only, not investment advice.** This pack does research support only: no trading, no price prediction, no paid/login-walled sources.
+
+## Compatibility
+
+- DeepSeek Harness `0.1.0-rc.6` (peers pinned to `0.1.0-rc.6`).
+- Node `^22.19.0 || >=24.0.0`, ESM only (`"type": "module"`).
+- Peer dependencies: `@deepseek-ai/cordis ^4.0.1`, `@deepseek-ai/schemastery ^3.18.0`, and `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-skill`, `@deepseek-ai/dsh-skill-filesystem` at `0.1.0-rc.6` (all composed by the official `dsh-base` bundle).
+- Optional, looked up at execution time (never injected): `ctx.web` (public-source retrieval — composed by `dsh-base`) and `ctx.researchReport` (the sibling `dsh-research-report` sealing engine).
+
+## What you get
+
+- **`industry_map`** — build or update an industry chain map (`chain.json`): upstream/midstream/downstream nodes, edges, and metric slots. A metric with a `value` must carry a `sourceRef`; a value-less slot is an explicit gap. Seed notes/files and an optional `ctx.web` digest are registered as citable sources (`S1`, `S2`, …).
+- **`industry_track`** — public-source policy/news tracking over the official `ctx.web` seam: per-topic search, host allow/block lists, `since` filtering, bounded snapshot fetches with SHA-256 provenance hashes, and append + dedupe into `timeline.jsonl` with a retention cap. Fails loud when the web capability is unreachable.
+- **`company_scan`** — company cards (`card.json` + `card.md`) from your workspace data files (SHA-256-hashed, with Markdown outlines and figure-candidate lines so every number cites a file and a line), plus an optional `ctx.web` citation complement. Text formats only in v1 (no PDF).
+- **`industry_report`** — one auditable report from the map + timeline + cards. With a mounted `ctx.researchReport` engine the evidence/sections/claims are sealed by its `assemble` and per-claim verdicts come back; without one, the builtin fallback writes versioned `reports/<YYYYMMDD-HHmmss>/report.md` + `manifest.json` with a SHA-256 source-traceability table and honestly labels `engine: 'builtin-fallback'`.
+- **Two methodology skills** — `industry-research-method` (chain decomposition, supply/demand framework, sourcing discipline, gap-declaration discipline) and `company-research-method` (company framework, public-source list, compliance wording).
+- **Typed Cordis events** — `industry-research/map`, `industry-research/track`, `industry-research/report` emitted after each committed artifact.
+
+## Quick start
+
+### git channel
+
+```sh
+# From a scratch profile (pins the commit; runs the self-contained `prepare` build)
+dsh plugin --profile demo add "github:PerryLink/dsh-industry-research#<sha>"
+# The profile's pnpm-workspace.yaml gains an allowBuilds entry for dsh-industry-research on first add.
+```
+
+### npm channel
+
+```sh
+dsh plugin --profile demo add dsh-industry-research
+```
+
+Both channels install the bundle row (see `cordis.patch.yml`) into the profile's `dsh.profile.bundles` stack and take effect on restart.
+
+Then, in a session:
+
+```
+加载 industry-research-method 技能，然后研究白酒行业：
+先 industry_map 建产业链图，再 industry_track 跟踪政策，最后 industry_report 出报告。
+```
+
+## Install & uninstall
+
+```sh
+dsh plugin --profile demo add dsh-industry-research       # install
+dsh plugin --profile demo remove dsh-industry-research    # uninstall
+```
+
+Verify the row mounts: `dsh --profile demo --dump-config | grep dsh-industry-research`.
+
+## Configuration
+
+All tunables are Schemastery `Config` fields; invalid values fail the profile load loudly.
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch; `false` mounts nothing. |
+| `industryRoot` | `industry-research` | Artifact root, relative to the session workspace (or absolute). |
+| `fetchTimeoutMs` | `20000` | Per-request timeout (ms) for `ctx.web` search/fetch calls. |
+| `timelineMaxEntries` | `500` | Entries retained per industry `timeline.jsonl` (oldest dropped). |
+| `sourceAllowlist` | `[]` | Host allowlist for tracked sources (empty = all hosts). |
+| `sourceBlocklist` | `[]` | Host blocklist for tracked sources (wins over the allowlist). |
+| `offline` | `false` | Offline mode: never touch `ctx.web`; local workspace data only. |
+| `skillsDir` | _(unset)_ | Explicit skills root override; defaults to the packaged `skills/`. |
+| `track.maxResultsPerTopic` | `10` | `web_search` maxResults per topic. |
+| `track.maxFetchesPerCall` | `10` | Snapshot-fetch budget per `industry_track` call. |
+| `scan.maxFileBytes` | `1048576` | Per-file read cap for company data files. |
+| `scan.maxFigureCandidates` | `100` | Figure-candidate budget per company scan. |
+
+## Tools & surfaces
+
+### `industry_map({ industry, seed?, seedFiles?, web?, chain? })`
+
+Called with `chain`: validates (dangling edges, unsourced values, illegal tiers, duplicate ids — loud failure with the full issue list) and persists `chain.json`, then lists the explicit gap slots. Called without `chain`: returns the current map, the registered sources, and an optional `ctx.web` chain-structure digest so the model can iterate. Emits `industry-research/map`.
+
+### `industry_track({ industry, topics?, since? })`
+
+Searches each topic through `ctx.web`, filters by the allow/block lists and `since`, fetches page snapshots (SHA-256) within the call budget, and merges into `timeline.jsonl` (dedupe by normalized URL, capped). Sources whose snapshot failed are kept as citation-only entries with the reason in `note`. Fails loud naming the missing capability when `ctx.web` is unmounted or `offline: true`. Emits `industry-research/track`.
+
+### `company_scan({ name, dataFiles?, web? })`
+
+Reads the workspace data files (`.md/.txt/.csv/.tsv/.json`; v1 does not parse PDF), hashes them, extracts Markdown outlines and figure-candidate lines, optionally attaches `ctx.web` citations, and persists the card. Rejected files come back with reasons; everything the card cannot establish is an explicit gap.
+
+### `industry_report({ industry, sections?, companies?, draft? })`
+
+Assembles evidence (`E-chain`, `E-timeline`, `E-company-<slug>`) and either validates your `draft` (sections + claims; every claim's `evidenceIds` must reference registered evidence) or builds the mechanical auto-draft (sourced metrics and recent timeline entries become claims). Engine path: sealed directory + `sealHash` + per-claim verdicts. Fallback path: versioned Markdown + manifest, claims honestly marked `unverified`. Emits `industry-research/report`.
+
+## Skills
+
+- **`industry-research-method`** — industry research methodology: upstream/midstream/downstream decomposition, supply/demand framework, sourcing discipline (every number: value + unit + source + asOf), and gap-declaration discipline (declare, never fabricate).
+- **`company-research-method`** — company research methodology: the business-structure / financials / risks card framework, the public-source priority list (company disclosures → regulators → authoritative media), and compliance wording.
+
+Both load on demand through the standard `skill` tool (`加载 industry-research-method 技能`).
+
+## Data layout
+
+```
+<workspace>/<industryRoot>/<industry>/chain.json      industry_map
+<workspace>/<industryRoot>/<industry>/timeline.jsonl  industry_track
+<workspace>/<industryRoot>/<industry>/sources.json    citable source registry (S1, S2, …)
+<workspace>/<industryRoot>/<industry>/notes/          seed notes
+<workspace>/<industryRoot>/<industry>/reports/<ts>/   industry_report (report.md + manifest.json)
+<workspace>/<industryRoot>/companies/<name>/card.*    company_scan
+```
+
+## Permissions & data
+
+`dsh-industry-research` consumes only public seams: `ctx.tools`, `ctx.skills`, and — looked up optionally — `ctx.web` and `ctx.researchReport`. It performs no network access of its own (all retrieval goes through `ctx.web` with the deployment's provider selection and your configured timeouts), stores no credentials, and writes only inside the session workspace under `industryRoot`. Only public sources are used; paid or login-walled sources are out of scope — pass your own exports in as `dataFiles`.
+
+## Security boundaries
+
+- **Workspace containment** — industry/company names are validated path segments; data files are containment-checked against the session cwd (both sides resolved).
+- **Provenance by construction** — sources carry SHA-256 hashes; unsourced numbers are validation errors; corrupt timeline lines are skipped with a surfaced count, never silently.
+- **Honest degradation** — missing `ctx.web` / `ctx.researchReport` produce loud failures or honestly labeled fallback artifacts, never silent fabrication.
+- **Reversible registrations** — everything goes through `ctx.effect()` / `ctx.on()` / `register()`.
+- **Research-only compliance** — tool descriptions, cards, and reports carry 「仅供研究，不构成投资建议」; data points carry asOf and sources.
+
+## Known limitations
+
+- **Cordis events, not session-log events** — the rc.6 `Session.append` signature has no `ignorable` marker for out-of-repo event types and no external event-registration surface, so appending custom `industry-research/*` session events would make the persistence coordinator refuse the log on restore. The durable record is the workspace artifacts; observability rides the typed Cordis events; model-visible tool results ride the durable `tool/result` session event.
+- **No `ctx.attachment` writes** — the rc.6 attachment seam accepts images only (PNG/JPEG/WebP/GIF); Markdown reports therefore stay versioned workspace files, referenced by absolute path in the tool result.
+- **v1 reads text formats only** — no PDF parsing; ask users to convert PDFs to text/Markdown first.
+- **Chinese-edition skills** — the packaged methodology skills ship in Chinese; an English edition is future work.
+- **Foreground tools** — `industry_track` is bounded by `track.maxFetchesPerCall` and `fetchTimeoutMs` and runs in the foreground; a background-jobs mode is future work.
+- **The auto-draft is mechanical** — it summarizes artifacts and turns sourced data points into claims; narrative quality comes from model-authored `draft`s.
+
+## Development
+
+```sh
+pnpm install
+pnpm run typecheck && pnpm run typecheck:ci
+pnpm test
+pnpm run build
+pnpm run verify:self-contained && pnpm run verify:artifacts
+pnpm run verify:readme-sync
+pnpm run pack:check
+```
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `cordis`, `industry-research`, `company-research`, `research`, `report`
+
+## Contributors
+
+- Initial design and implementation by the `dsh-industry-research` development session (DeepSeek Harness).
+
+External contributions are welcome — open an issue or a pull request.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

package/README.pt.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# 🏭 dsh-industry-research
+
+**Pacote de domínio para pesquisa de indústrias e empresas no DeepSeek Harness.**
+
+*Mapas de cadeia industrial, acompanhamento de fontes públicas, cartões de empresa e relatórios auditáveis — cada número remonta a uma fonte, cada lacuna é declarada.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-industry-research/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-industry-research/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-industry-research?label=version)](https://github.com/PerryLink/dsh-industry-research/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-industry-research)](https://www.npmjs.com/package/dsh-industry-research)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-industry-research)](https://www.npmjs.com/package/dsh-industry-research)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+**仅供研究，不构成投资建议 — Apenas para pesquisa; não constitui aconselhamento de investimento.** Este pacote só apoia pesquisa: sem trading, sem previsão de preços, sem fontes pagas ou com login.
+
+## Compatibility
+
+- DeepSeek Harness `0.1.0-rc.6` (peers fixados em `0.1.0-rc.6`).
+- Node `^22.19.0 || >=24.0.0`, apenas ESM (`"type": "module"`).
+- Dependências peer: `@deepseek-ai/cordis ^4.0.1`, `@deepseek-ai/schemastery ^3.18.0`, e `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-skill`, `@deepseek-ai/dsh-skill-filesystem` em `0.1.0-rc.6` (todas compostas pelo bundle oficial `dsh-base`).
+- Capacidades opcionais, resolvidas em tempo de execução (nunca injetadas): `ctx.web` (recuperação de fontes públicas, composta pelo `dsh-base`) e `ctx.researchReport` (o motor de selagem do plugin irmão `dsh-research-report`).
+
+## What you get
+
+- **`industry_map`** — cria ou atualiza um mapa de cadeia industrial (`chain.json`): nós upstream/midstream/downstream, arestas e slots de métricas. Uma métrica com `value` exige `sourceRef`; um slot sem valor é uma lacuna explícita. Notas/arquivos-semente e um resumo opcional do `ctx.web` são registrados como fontes citáveis (`S1`, `S2`, …).
+- **`industry_track`** — acompanhamento de políticas e notícias de fontes públicas pela costura oficial `ctx.web`: busca por tópico, listas de hosts permitidos/bloqueados, filtro `since`, capturas de snapshots limitadas com hashes SHA-256 de proveniência, e fusão com deduplicação em `timeline.jsonl` com teto de retenção. Falha em voz alta quando a capacidade web está inalcançável.
+- **`company_scan`** — cartões de empresa (`card.json` + `card.md`) a partir dos seus arquivos de dados do workspace (hash SHA-256, esboços Markdown e linhas candidatas de números para que cada número cite arquivo e linha), com complemento opcional de citações `ctx.web`. Apenas formatos de texto na v1 (sem PDF).
+- **`industry_report`** — um relatório auditável a partir do mapa + linha do tempo + cartões. Com o motor `ctx.researchReport` montado, evidência/seções/claims são seladas pelo seu `assemble` e os veredictos por claim retornam; sem ele, a rota integrada escreve `reports/<YYYYMMDD-HHmmss>/report.md` + `manifest.json` versionados com tabela de rastreabilidade SHA-256 e rotula honestamente `engine: 'builtin-fallback'`.
+- **Duas skills de metodologia** — `industry-research-method` (decomposição da cadeia, estrutura oferta/demanda, disciplina de fontes, disciplina de declaração de lacunas) e `company-research-method` (estrutura de empresa, lista de fontes públicas, redação de conformidade).
+- **Eventos Cordis tipados** — `industry-research/map`, `industry-research/track`, `industry-research/report` emitidos após cada artefato confirmado.
+
+## Quick start
+
+### Canal git
+
+```sh
+# A partir de um profile temporário (fixa o commit; executa o build `prepare` autocontido)
+dsh plugin --profile demo add "github:PerryLink/dsh-industry-research#<sha>"
+# O pnpm-workspace.yaml do profile ganha uma entrada allowBuilds para dsh-industry-research no primeiro add.
+```
+
+### Canal npm
+
+```sh
+dsh plugin --profile demo add dsh-industry-research
+```
+
+Ambos os canais instalam a linha do bundle (ver `cordis.patch.yml`) na pilha `dsh.profile.bundles` do profile e fazem efeito ao reiniciar.
+
+Depois, numa sessão:
+
+```
+加载 industry-research-method 技能，然后研究白酒行业：
+先 industry_map 建产业链图，再 industry_track 跟踪政策，最后 industry_report 出报告。
+```
+
+## Install & uninstall
+
+```sh
+dsh plugin --profile demo add dsh-industry-research       # instalar
+dsh plugin --profile demo remove dsh-industry-research    # desinstalar
+```
+
+Verifique se a linha monta: `dsh --profile demo --dump-config | grep dsh-industry-research`.
+
+## Configuration
+
+Todos os ajustes são campos `Config` de Schemastery; valores inválidos falham ruidosamente ao carregar o profile.
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `enabled` | `true` | Interruptor mestre; `false` não monta nada. |
+| `industryRoot` | `industry-research` | Raiz de artefatos, relativa ao workspace da sessão (ou absoluta). |
+| `fetchTimeoutMs` | `20000` | Tempo limite por requisição (ms) para chamadas `ctx.web`. |
+| `timelineMaxEntries` | `500` | Entradas retidas por `timeline.jsonl` (as mais antigas são descartadas). |
+| `sourceAllowlist` | `[]` | Lista de hosts permitidos (vazia = todos). |
+| `sourceBlocklist` | `[]` | Lista de hosts bloqueados (prevalece sobre a permitida). |
+| `offline` | `false` | Modo offline: nunca toca `ctx.web`; apenas dados locais. |
+| `skillsDir` | _(não definido)_ | Raiz de skills explícita; por padrão o `skills/` empacotado. |
+| `track.maxResultsPerTopic` | `10` | maxResults do `web_search` por tópico. |
+| `track.maxFetchesPerCall` | `10` | Orçamento de capturas por chamada `industry_track`. |
+| `scan.maxFileBytes` | `1048576` | Teto de leitura por arquivo de dados de empresa. |
+| `scan.maxFigureCandidates` | `100` | Orçamento de linhas candidatas por varredura. |
+
+## Tools & surfaces
+
+### `industry_map({ industry, seed?, seedFiles?, web?, chain? })`
+
+Com `chain`: valida (arestas pendentes, valores sem fonte, tiers ilegais, ids duplicados — falha ruidosa com a lista completa) e persiste `chain.json`, depois lista as lacunas explícitas. Sem `chain`: devolve o mapa atual, as fontes registradas e um resumo opcional de estrutura via `ctx.web` para iterar. Emite `industry-research/map`.
+
+### `industry_track({ industry, topics?, since? })`
+
+Busca cada tópico via `ctx.web`, filtra pelas listas e `since`, captura snapshots (SHA-256) dentro do orçamento e funde em `timeline.jsonl` (deduplicação por URL normalizada, com teto). Fontes cujo snapshot falhou são mantidas como entradas só-citação com a razão em `note`. Falha em voz alta nomeando a capacidade ausente quando `ctx.web` não está montada ou `offline: true`. Emite `industry-research/track`.
+
+### `company_scan({ name, dataFiles?, web? })`
+
+Lê os arquivos de dados do workspace (`.md/.txt/.csv/.tsv/.json`; v1 não analisa PDF), calcula hashes, extrai esboços Markdown e linhas candidatas de números, anexa citações `ctx.web` opcionais e persiste o cartão. Arquivos rejeitados retornam com razões; tudo o que o cartão não consegue estabelecer é uma lacuna explícita.
+
+### `industry_report({ industry, sections?, companies?, draft? })`
+
+Reúne a evidência (`E-chain`, `E-timeline`, `E-company-<slug>`) e valida o seu `draft` (seções + claims; cada `evidenceIds` deve referenciar evidência registrada) ou constrói o rascunho mecânico (métricas com fonte e entradas recentes viram claims). Rota do motor: diretório selado + `sealHash` + veredictos por claim. Rota integrada: Markdown versionado + manifesto, claims honestamente marcados `unverified`. Emite `industry-research/report`.
+
+## Skills
+
+- **`industry-research-method`** — metodologia de pesquisa industrial: decomposição upstream/midstream/downstream, estrutura oferta/demanda, disciplina de fontes (cada número: valor + unidade + fonte + asOf) e disciplina de lacunas (declarar, nunca fabricar).
+- **`company-research-method`** — metodologia de pesquisa de empresas: estrutura de negócio / finanças / riscos, lista de prioridade de fontes públicas (divulgações da empresa → reguladores → mídia autorizada) e redação de conformidade.
+
+Ambas carregam sob demanda pela ferramenta padrão `skill` (`加载 industry-research-method 技能`).
+
+## Data layout
+
+```
+<workspace>/<industryRoot>/<indústria>/chain.json      industry_map
+<workspace>/<industryRoot>/<indústria>/timeline.jsonl  industry_track
+<workspace>/<industryRoot>/<indústria>/sources.json    registro de fontes citáveis (S1, S2, …)
+<workspace>/<industryRoot>/<indústria>/notes/          notas-semente
+<workspace>/<industryRoot>/<indústria>/reports/<ts>/   industry_report (report.md + manifest.json)
+<workspace>/<industryRoot>/companies/<empresa>/card.*  company_scan
+```
+
+## Permissions & data
+
+`dsh-industry-research` consome apenas costuras públicas: `ctx.tools`, `ctx.skills` e — resolvidas opcionalmente — `ctx.web` e `ctx.researchReport`. Não realiza acesso de rede próprio (toda recuperação passa por `ctx.web` com a seleção de provedor do deployment e os seus tempos limite configurados), não armazena credenciais e só escreve dentro do workspace da sessão sob `industryRoot`. Apenas fontes públicas são usadas; fontes pagas ou com login estão fora do escopo — passe as suas próprias exportações como `dataFiles`.
+
+## Security boundaries
+
+- **Contenção no workspace** — nomes de indústria/empresa validados como segmentos de caminho; arquivos de dados verificados contra o cwd da sessão (ambos os lados resolvidos).
+- **Proveniência por construção** — fontes carregam hashes SHA-256; números sem fonte são erros de validação; linhas corrompidas da linha do tempo são ignoradas com contagem visível, nunca em silêncio.
+- **Degradação honesta** — a ausência de `ctx.web` / `ctx.researchReport` produz falhas ruidosas ou artefatos fallback honestamente rotulados, nunca fabricação silenciosa.
+- **Registros reversíveis** — tudo passa por `ctx.effect()` / `ctx.on()` / `register()`.
+- **Conformidade apenas-pesquisa** — descrições de ferramentas, cartões e relatórios carregam 「仅供研究，不构成投资建议」; os dados carregam asOf e fontes.
+
+## Known limitations
+
+- **Eventos Cordis, não eventos de log de sessão** — a assinatura `Session.append` do rc.6 não tem marcador `ignorable` para tipos de evento externos nem superfície de registro externa, portanto anexar eventos de sessão `industry-research/*` faria o coordenador de persistência recusar o log na restauração. O registro duradouro são os artefatos do workspace; a observabilidade viaja pelos eventos Cordis tipados; os resultados de ferramentas visíveis ao modelo viajam pelo evento duradouro `tool/result`.
+- **Sem escritas em `ctx.attachment`** — a costura de anexos do rc.6 só aceita imagens (PNG/JPEG/WebP/GIF); os relatórios Markdown permanecem como arquivos versionados do workspace, referenciados por caminho absoluto no resultado da ferramenta.
+- **v1 só lê formatos de texto** — sem análise de PDF; peça aos usuários para converter os PDFs em texto/Markdown primeiro.
+- **Skills em edição chinesa** — as skills de metodologia empacotadas são publicadas em chinês; uma edição em inglês é trabalho futuro.
+- **Ferramentas em primeiro plano** — `industry_track` é limitada por `track.maxFetchesPerCall` e `fetchTimeoutMs` e corre em primeiro plano; um modo com trabalhos em segundo plano é trabalho futuro.
+- **O rascunho automático é mecânico** — resume artefatos e converte dados com fonte em claims; a qualidade narrativa vem dos `draft` escritos pelo modelo.
+
+## Development
+
+```sh
+pnpm install
+pnpm run typecheck && pnpm run typecheck:ci
+pnpm test
+pnpm run build
+pnpm run verify:self-contained && pnpm run verify:artifacts
+pnpm run verify:readme-sync
+pnpm run pack:check
+```
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `cordis`, `industry-research`, `company-research`, `research`, `report`
+
+## Contributors
+
+- Design e implementação iniciais pela sessão de desenvolvimento de `dsh-industry-research` (DeepSeek Harness).
+
+Contribuições externas são bem-vindas — abra uma issue ou um pull request.
+
+## License
+
+Apache-2.0 — veja [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# 🏭 dsh-industry-research
+
+**DeepSeek Harness 的行业/公司研究领域包。**
+
+*产业链建图、公开源跟踪、公司速览卡、可核查报告——每个数字都能回溯来源，每个缺口都如实声明。*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-industry-research/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-industry-research/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-industry-research?label=version)](https://github.com/PerryLink/dsh-industry-research/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-industry-research)](https://www.npmjs.com/package/dsh-industry-research)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-industry-research)](https://www.npmjs.com/package/dsh-industry-research)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+**仅供研究，不构成投资建议。** 本包只做研究支持：不接交易、不预测价格、不使用付费/需登录数据源。
+
+## Compatibility
+
+- DeepSeek Harness `0.1.0-rc.6`（peer 钉版 `0.1.0-rc.6`）。
+- Node `^22.19.0 || >=24.0.0`，仅 ESM（`"type": "module"`）。
+- Peer 依赖：`@deepseek-ai/cordis ^4.0.1`、`@deepseek-ai/schemastery ^3.18.0`，以及 `0.1.0-rc.6` 的 `@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-skill`、`@deepseek-ai/dsh-skill-filesystem`（官方 `dsh-base` bundle 均已组合）。
+- 可选能力在执行时查找（绝不注入）：`ctx.web`（公开源检索，`dsh-base` 已组合）与 `ctx.researchReport`（兄弟插件 `dsh-research-report` 的封存引擎）。
+
+## What you get
+
+- **`industry_map`**——构建/更新产业链结构图（`chain.json`）：上/中/下游节点、边、指标槽位。带 `value` 的指标必须带 `sourceRef`；无值槽位即显式缺口。种子笔记/文件与可选 `ctx.web` 摘要登记为可引用来源（`S1`、`S2`……）。
+- **`industry_track`**——经官方 `ctx.web` 缝隙跟踪行业政策/要闻：按主题检索、来源主机白/黑名单、`since` 过滤、预算内快照抓取（SHA-256 溯源哈希），追加去重写入 `timeline.jsonl`（保留上限可配）。web 能力不可达时响亮失败。
+- **`company_scan`**——以工作区数据文件生成公司速览卡（`card.json` + `card.md`）：SHA-256 哈希、Markdown 大纲、数字候选行（每个数字可标注文件与行号），另可选 `ctx.web` 引用补充。v1 只读文本格式（不解析 PDF）。
+- **`industry_report`**——汇总结构图、时间线与公司卡产出可核查报告。挂载 `ctx.researchReport` 引擎时证据/章节/claims 提交其 `assemble` 封存并回传逐 claim 结论；缺席时内置降级路径写入版本化 `reports/<YYYYMMDD-HHmmss>/report.md` + `manifest.json`（含 SHA-256 来源回溯表），并如实标注 `engine: 'builtin-fallback'`。
+- **两个方法论技能**——`industry-research-method`（产业链拆分、供需框架、口径纪律、缺口声明纪律）与 `company-research-method`（公司研究框架、公开源清单、合规话术）。
+- **类型化 Cordis 事件**——每份产物落盘后发出 `industry-research/map`、`industry-research/track`、`industry-research/report`。
+
+## Quick start
+
+### git 渠道
+
+```sh
+# 在临时 profile 中（钉 commit；运行自包含 prepare 构建）
+dsh plugin --profile demo add "github:PerryLink/dsh-industry-research#<sha>"
+# 首次 add 时 profile 的 pnpm-workspace.yaml 会加入 dsh-industry-research 的 allowBuilds 条目。
+```
+
+### npm 渠道
+
+```sh
+dsh plugin --profile demo add dsh-industry-research
+```
+
+两条渠道都会把 bundle 行（见 `cordis.patch.yml`）装入 profile 的 `dsh.profile.bundles` 栈，重启生效。
+
+然后在会话中：
+
+```
+加载 industry-research-method 技能，然后研究白酒行业：
+先 industry_map 建产业链图，再 industry_track 跟踪政策，最后 industry_report 出报告。
+```
+
+## Install & uninstall
+
+```sh
+dsh plugin --profile demo add dsh-industry-research       # 安装
+dsh plugin --profile demo remove dsh-industry-research    # 卸载
+```
+
+验证行已挂载：`dsh --profile demo --dump-config | grep dsh-industry-research`。
+
+## Configuration
+
+全部可调项均为 Schemastery `Config` 字段；非法值在加载期响亮失败。
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `enabled` | `true` | 总开关；`false` 不挂载任何能力。 |
+| `industryRoot` | `industry-research` | 产物根目录（相对会话工作区，或绝对路径）。 |
+| `fetchTimeoutMs` | `20000` | `ctx.web` 检索/抓取的单次请求超时（毫秒）。 |
+| `timelineMaxEntries` | `500` | 每个行业 `timeline.jsonl` 的保留条数（最旧先弃）。 |
+| `sourceAllowlist` | `[]` | 跟踪来源主机白名单（空 = 全部允许）。 |
+| `sourceBlocklist` | `[]` | 跟踪来源主机黑名单（优先于白名单）。 |
+| `offline` | `false` | 离线模式：不触网，只用本地工作区数据。 |
+| `skillsDir` | _(未设置)_ | 显式 skills 根目录覆盖；缺省用随包 `skills/`。 |
+| `track.maxResultsPerTopic` | `10` | 每个主题的 `web_search` maxResults。 |
+| `track.maxFetchesPerCall` | `10` | 每次 `industry_track` 调用的快照抓取预算。 |
+| `scan.maxFileBytes` | `1048576` | 公司数据文件的单文件读取上限（字节）。 |
+| `scan.maxFigureCandidates` | `100` | 每次公司扫描的数字候选行预算。 |
+
+## Tools & surfaces
+
+### `industry_map({ industry, seed?, seedFiles?, web?, chain? })`
+
+带 `chain` 调用：校验（悬空边、无来源数值、非法 tier、重复 id——带完整问题清单响亮失败）并落盘 `chain.json`，随后列出显式缺口槽位。不带 `chain` 调用：返回当前图、已登记来源与可选 `ctx.web` 产业链结构摘要，供模型迭代。发出 `industry-research/map` 事件。
+
+### `industry_track({ industry, topics?, since? })`
+
+经 `ctx.web` 逐主题检索，按白/黑名单与 `since` 过滤，在调用预算内抓取页面快照（SHA-256），合并进 `timeline.jsonl`（按规范化 URL 去重，保留上限）。快照失败的来源以纯引用条目保留并在 `note` 中说明原因。`ctx.web` 未挂载或 `offline: true` 时响亮失败并指明缺失能力。发出 `industry-research/track` 事件。
+
+### `company_scan({ name, dataFiles?, web? })`
+
+读取工作区数据文件（`.md/.txt/.csv/.tsv/.json`；v1 不解析 PDF），计算哈希，提取 Markdown 大纲与数字候选行，可选附加 `ctx.web` 引用，落盘速览卡。未采纳文件带原因返回；卡片无法确立的内容一律写入显式缺口。
+
+### `industry_report({ industry, sections?, companies?, draft? })`
+
+组装证据（`E-chain`、`E-timeline`、`E-company-<slug>`），或校验你提供的 `draft`（章节 + claims；每条 claim 的 `evidenceIds` 必须引用已登记证据），或机械自动生成草稿（有来源的指标与近期时间线条目生成 claims）。引擎路径：封存目录 + `sealHash` + 逐 claim 结论。降级路径：版本化 Markdown + manifest，claims 如实标记 `unverified`。发出 `industry-research/report` 事件。
+
+## Skills
+
+- **`industry-research-method`**——行业研究方法论：上/中/下游拆分、供需框架、口径纪律（每个数字：数值 + 单位 + 来源 + asOf）、缺口声明纪律（如实声明，绝不编造）。
+- **`company-research-method`**——公司研究方法论：业务结构/财务要点/风险点卡片框架、公开源优先级清单（公司披露 → 监管 → 权威媒体）、合规话术。
+
+两个技能经标准 `skill` 工具按需加载（`加载 industry-research-method 技能`）。
+
+## Data layout
+
+```
+<工作区>/<industryRoot>/<行业>/chain.json      industry_map
+<工作区>/<industryRoot>/<行业>/timeline.jsonl  industry_track
+<工作区>/<industryRoot>/<行业>/sources.json    可引用来源登记（S1、S2……）
+<工作区>/<industryRoot>/<行业>/notes/          种子笔记
+<工作区>/<industryRoot>/<行业>/reports/<ts>/   industry_report（report.md + manifest.json）
+<工作区>/<industryRoot>/companies/<公司>/card.*  company_scan
+```
+
+## Permissions & data
+
+`dsh-industry-research` 只消费公开缝隙：`ctx.tools`、`ctx.skills`，以及可选查找的 `ctx.web` 与 `ctx.researchReport`。本插件自身不发起任何网络访问（一切检索经 `ctx.web`，provider 选择与超时由部署方与你的配置决定），不存凭据，只在会话工作区的 `industryRoot` 下写文件。只使用公开源；付费/需登录数据源不在范围内——请自行导出后作为 `dataFiles` 传入。
+
+## Security boundaries
+
+- **工作区隔离**——行业/公司名校验为单一路径段；数据文件对照会话 cwd 做包含性检查（双侧 resolve）。
+- **构造即溯源**——来源带 SHA-256 哈希；无来源数字即校验错误；损坏时间线行跳过且计数如实上报，绝不静默。
+- **诚实降级**——缺少 `ctx.web` / `ctx.researchReport` 时响亮失败或产出如实标注的降级产物，绝不静默编造。
+- **可逆注册**——一切贡献经 `ctx.effect()` / `ctx.on()` / `register()`。
+- **纯研究合规**——工具描述、卡片与报告均带「仅供研究，不构成投资建议」；数据点带 asOf 与来源。
+
+## Known limitations
+
+- **Cordis 事件而非会话日志事件**——rc.6 的 `Session.append` 签名没有 `ignorable` 标记（非 surface 事件 `...opts: []`），也没有外部事件注册面；追加自定义 `industry-research/*` 会话事件会导致持久化协调器在恢复时拒绝该日志。持久记录是工作区产物本身；可观测性走类型化 Cordis 事件；模型可见的工具结果走持久 `tool/result` 会话事件。
+- **不写 `ctx.attachment`**——rc.6 附件缝隙只接受图片（PNG/JPEG/WebP/GIF）；Markdown 报告因此保持为版本化工作区文件，工具结果中以绝对路径引用。
+- **v1 只读文本格式**——不解析 PDF；请用户先把 PDF 转成文本/Markdown。
+- **中文版技能**——随包方法论技能为中文版；英文版为后续工作。
+- **前台工具**——`industry_track` 由 `track.maxFetchesPerCall` 与 `fetchTimeoutMs` 界定为前台任务；后台任务模式为后续工作。
+- **自动草稿是机械组装**——它汇总产物并把有来源的数据点生成 claims；叙述质量来自模型撰写的 `draft`。
+
+## Development
+
+```sh
+pnpm install
+pnpm run typecheck && pnpm run typecheck:ci
+pnpm test
+pnpm run build
+pnpm run verify:self-contained && pnpm run verify:artifacts
+pnpm run verify:readme-sync
+pnpm run pack:check
+```
+
+## Topics
+
+`dsh`、`dsh-plugin`、`deepseek-harness`、`cordis`、`industry-research`、`company-research`、`research`、`report`
+
+## Contributors
+
+- 初始设计与实现：`dsh-industry-research` 开发会话（DeepSeek Harness）。
+
+欢迎外部贡献 —— 提交 issue 或 pull request。
+
+## License
+
+Apache-2.0 — 见 [LICENSE](LICENSE)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,21 @@
+# Third-party notices
+
+`dsh-industry-research` bundles no third-party source code. All TypeScript/JavaScript
+sources in this repository are original works by the dsh-industry-research contributors,
+licensed under Apache-2.0 (see `LICENSE`).
+
+The package depends on the following software. None of it is bundled into the
+published tarball except where noted; these are install-time dependencies:
+
+| Package | Version range | License | Purpose |
+|---|---|---|---|
+| [tsdown](https://github.com/rolldown/tsdown) | `^0.22.14` | MIT | Build-time bundling of `lib/` (a regular dependency so the git-install channel's `prepare` script can build) |
+| [typescript](https://github.com/microsoft/TypeScript) | `^5.9.0` | Apache-2.0 | Build-time declaration emission (`lib/types/`) |
+| [@deepseek-ai/cordis](https://www.npmjs.com/package/@deepseek-ai/cordis) | `^4.0.1` (peer) | See package | The plugin runtime |
+| [@deepseek-ai/schemastery](https://www.npmjs.com/package/@deepseek-ai/schemastery) | `^3.18.0` (peer) | See package | Configuration schema |
+| `@deepseek-ai/dsh-*` peers | `0.1.0-rc.6` (peer) | See packages | Official harness seams (`dsh-tools`, `dsh-skill`, `dsh-skill-filesystem`) |
+
+At runtime the plugin talks to the harness services listed as peerDependencies
+plus the optional `ctx.web` and `ctx.researchReport` capabilities (looked up
+structurally); it performs no network requests of its own and stores no
+credentials.

package/cordis.patch.yml

@@ -0,0 +1,44 @@
+# dsh-industry-research bundle patch: mount the industry/company research pack.
+#
+# Every key below is a Config field (Schemastery schema); invalid values fail
+# the profile load loudly. See README.md "Configuration" for the full table.
+# The `skills` and `tools` services come from the profile's base bundle
+# (dsh-base composes dsh-skill + dsh-skill-filesystem + dsh-tools); the web
+# capability (ctx.web) and the report engine (ctx.researchReport) are optional
+# and looked up at execution time, never injected.
+- insert:
+    - id: dsh-industry-research
+      name: dsh-industry-research
+      config:
+        # Master switch. On by default; `false` mounts nothing at all.
+        enabled: true
+        # Root directory (relative to the session workspace, or absolute) that
+        # holds every industry artifact: <industryRoot>/<industry>/chain.json,
+        # timeline.jsonl, sources.json, reports/, plus shared company cards
+        # under <industryRoot>/companies/<name>/.
+        industryRoot: industry-research
+        # Per-request timeout (ms) applied to ctx.web search/fetch calls.
+        fetchTimeoutMs: 20000
+        # Maximum entries retained per industry timeline.jsonl (oldest dropped).
+        timelineMaxEntries: 500
+        # Host allowlist for tracked sources (empty = all hosts allowed).
+        sourceAllowlist: []
+        # Host blocklist for tracked sources (wins over the allowlist).
+        sourceBlocklist: []
+        # Offline mode: never touch ctx.web; only local workspace data is used.
+        offline: false
+        # Explicit skills root override; empty = the packaged skills/ edition.
+        # skillsDir: ''
+        # Public-source tracking bounds.
+        track:
+          # web_search maxResults per topic.
+          maxResultsPerTopic: 10
+          # Maximum snapshot fetches per industry_track call (rest stay
+          # citation-only entries without a snapshot hash).
+          maxFetchesPerCall: 10
+        # Company scan bounds.
+        scan:
+          # Maximum bytes read per user-supplied data file.
+          maxFileBytes: 1048576
+          # Maximum figure-candidate lines surfaced per company scan.
+          maxFigureCandidates: 100