dsh-researchly 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tongfun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,31 @@
+# Researchly
+
+[中文](README.md) | English
+
+> Even with Li Lou’s keen eyesight and Gongshu’s skill, one cannot make true squares and circles without a square and compass. — *Mencius*, “Li Lou I”
+
+A DeepSeek Harness plugin that draws on George Pólya’s *How to Solve It* to guide agents through mathematical and physical research in four stages: understand, plan, execute, and review.
+
+## What it does
+
+This plugin guides the root agent through a strict, four-stage process for mathematical and physical research, aiming to reduce hallucinations and errors. If execution or review reveals a problem, the agent returns one or two stages to reconsider its approach. Only the problem statement and phase completion markers are kept in memory; research notes, summaries, and revision history are not stored.
+
+## The four stages
+
+To investigate a mathematical or physical problem, first establish what is sought, then devise a plan, carry it out, and finally review the result. The four stages are:
+
+1. **Understand (`understand`)** — clarify the problem, distinguish the known from the unknown, examine the conditions, and state the notation conventions.
+2. **Plan (`plan`)** — seek connections between the known and the unknown, and use them to devise an approach.
+3. **Execute (`execute`)** — follow the plan step by step, checking the reasoning at each step; if an obstruction prevents completing the calculation, return to the planning stage and revise the plan.
+4. **Review (`look_back`)** — verify the result, examine special cases, and try an independent derivation by another route.
+
+```mermaid
+flowchart TB
+    U["1. Understand"] --> P["2. Plan"] --> E["3. Execute"] --> L["4. Review"]
+
+    E -.->|"calculation obstructed"| P
+    L -.->|"execution error, omission, gap in reasoning, or insufficient precision"| E
+    L -.->|"invalid assumption, unsuitable method, or overlooked significant factor"| P
+```
+
+When a problem requires returning to an earlier stage, call `reopen` before marking the current phase complete. The target phase and all subsequent phases must be completed again. Only the three return paths shown above are allowed; once all four phases are complete, `reopen` can no longer be used. The model decides which phase to return to based on the cause; the tool checks that the transition is allowed and supplies the corresponding guidance.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# Researchly
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+中文 | [English](README.en.md)
+
+> 离娄之明，公输子之巧，不以规矩，不能成方圆。——《孟子·离娄上》
+
+本插件供 DeepSeek Harness 使用，参考 George Pólya 的书 *How to Solve It* 的方法，引导智能体依理解、规划、执行、复核四步研究数学、物理问题。
+
+## 用途
+
+本插件引导主智能体按严格的流程研究数学、物理问题，减轻幻觉，减少错误，依次完成四个阶段；执行或复核时若发现问题，便退回前一步或前两步，重新研究。内存中只保留题目及各阶段是否完成的记录，不保存研究笔记、摘要或历次修订。
+
+## 求解的四个阶段
+
+研究数学、物理问题，先须认清所求为何，继而拟定计划，加以执行，最后复核所得的结果。四步的要点如下：
+
+1. **understand（理解）** — 弄清题意，分辨已知与未知，审察条件，并说明符号约定。
+2. **plan（规划）** — 寻求已知与未知之间的联系，据以拟定求解的办法。
+3. **execute（执行）** — 依计划逐步进行，随时检查每一步的根据；若计算受阻，不能完成，便退回第二步，重拟计划。
+4. **look_back（复核）** — 检验所得的结果，考察特殊情形，并试从另一途径独立推导。
+
+```mermaid
+flowchart TB
+    U["1. 理解"] --> P["2. 规划"] --> E["3. 执行"] --> L["4. 复核"]
+
+    E -.->|"计算受阻"| P
+    L -.->|"执行有误、有所遗漏、论证不周或精度不足"| E
+    L -.->|"假设不成立、方法不合用或漏计重要因素"| P
+```
+
+发现问题而须退回时，应在本阶段尚未标为完成之前调用 `reopen`。从退回的阶段起，以下各阶段均须重新完成。退回的途径只限图中三种；四步全部完成以后，便不能再用此法退回。应退至哪一步，由模型按问题的原因决定；工具则检查这一转换是否合乎规定，并换用相应的提示词。

package/cordis.yml

@@ -0,0 +1,4 @@
+# Installation layer: resolve the package's built entry point.
+- insert:
+    - id: researchly
+      name: dsh-researchly

package/lib/index.js

@@ -0,0 +1,338 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/state.ts
+/**
+* Pure workflow state and transitions for the Researchly plugin.
+*
+* Keeping this logic free of Cordis makes the phase gates easy to test and
+* easy to reason about: each function receives a snapshot and returns the next
+* snapshot instead of mutating shared state.
+*
+* @module dsh-researchly/state
+*/
+const PHASES = [
+	"understand",
+	"plan",
+	"execute",
+	"look_back"
+];
+const PHASE_TITLES = {
+	understand: "Understanding the problem",
+	plan: "Devising a plan",
+	execute: "Carrying out, checking, and revising",
+	look_back: "Looking back"
+};
+/** Detailed phase-specific instructions, shown when that phase becomes active. */
+const PHASE_GUIDANCE = {
+	understand: `## Phase: Understanding the problem
+
+- Identify the principal parts: the unknown, the data, and the condition.
+- Clarify every word, definition, and convention. Search for unfamiliar terms.
+- Resolve physical and mathematical conventions explicitly, for example metric
+  signature, index order, coefficient conventions, and branch choices.
+- Decide whether the condition is sufficient, insufficient, redundant, or
+  contradictory. If it is insufficient, say exactly what is missing.
+- Use search and reference tools when definitions or conventions are uncertain.`,
+	plan: `## Phase: Devising a plan
+
+- Find a connection between the data and the unknown.
+- Ask whether you have seen the same or a related problem before.
+- Look at the unknown and think of familiar problems with the same kind of
+  unknown.
+- Use relevant theorems, properties, solved examples, and methods.
+- Introduce auxiliary elements, approximations, or analogous problems when the
+  direct connection is not visible.
+- Check that the plan uses all the data and the whole condition.
+- When returning here after an obstruction or a failed check, revise the plan
+  before completing this phase and returning to execution. First try to repair
+  the direct approach or choose a materially different direct approach.
+- If direct approaches repeatedly reach the same obstruction, use an auxiliary
+  problem: simplify, specialise, generalise, relax part of the condition,
+  change representation, or extract a transferable result.
+- Delegate independent exploration of candidate methods to focused subagents
+  when useful.`,
+	execute: `## Phase: Carrying out, checking, and revising
+
+1. Carry out the plan and check why each step is valid. A formal proof is not
+   necessary for every step; provide further justification when validity is unclear.
+2. If an obstruction prevents completing the calculation, identify it and call
+   research_workflow with action "reopen" and phase "plan". Do not mark execute
+   complete when the calculation cannot be completed.
+3. Revise the plan in Step 2, then complete plan before resuming execution.
+- Use computation tools for symbolic or numerical work, and delegate independent
+  calculations to focused subagents when helpful.`,
+	look_back: `## Phase: Looking back
+
+- Check the result with special and limiting cases.
+- Test dimensional consistency and expected signs or limits.
+- Check the argument step by step.
+- Try to derive the result differently, or see it at a glance.
+- If checking reveals execution errors, omissions, gaps in the argument, or
+  insufficient precision within the existing plan, return to Step 3 to correct
+  or complete the affected steps. Examples: the plan requires second order, but
+  only first order was calculated; a boundary condition was omitted.
+- If checking reveals invalid key assumptions, inapplicable methods, or missing
+  essential contributions in the existing plan, return to Step 2 to revise the
+  plan. Examples: non-degenerate perturbation theory was planned, but the energy
+  levels are degenerate; a neglected interaction is of the same order as retained
+  terms.
+- To return to Step 3 or Step 2, call research_workflow with action "reopen" and
+  phase "execute" or "plan", respectively. Explain the cause in your response.
+  Do not complete look_back after a failed check; repeat the affected phases and
+  check the corrected result before completing look_back.
+- Use a subagent for an independent verification when a different perspective
+  would be valuable.`
+};
+function assertPhase(phase) {
+	if (!PHASES.includes(phase)) throw new Error(`unknown phase "${phase}"`);
+}
+/** Start a new problem from a non-empty problem statement. */
+function startWorkflow(problem) {
+	const trimmed = problem.trim();
+	if (trimmed.length === 0) throw new Error("problem must be a non-empty description of the research problem");
+	return {
+		problem: trimmed,
+		completed: []
+	};
+}
+/** Whether every phase has been completed. */
+function isWorkflowComplete(state) {
+	return state.completed.length === PHASES.length;
+}
+/** The first incomplete phase, or undefined when the workflow is complete. */
+function nextPhase(state) {
+	return PHASES.find((phase) => !state.completed.includes(phase));
+}
+/**
+* Mark one phase complete.
+*
+* Phases must be completed in the order defined by {@link PHASES}. Duplicate
+* and out-of-order completions are programmer/model errors, so they throw.
+*/
+function completeWorkflowPhase(state, phase) {
+	assertPhase(phase);
+	if (state.completed.includes(phase)) throw new Error(`phase "${phase}" is already complete`);
+	const phaseIndex = PHASES.indexOf(phase);
+	const missing = PHASES.slice(0, phaseIndex).find((candidate) => !state.completed.includes(candidate));
+	if (missing !== void 0) throw new Error(`phase "${phase}" cannot complete before "${missing}"`);
+	return {
+		...state,
+		completed: [...state.completed, phase]
+	};
+}
+/** Reopen an earlier phase from the current, unfinished phase. */
+function reopenWorkflowPhase(state, phase) {
+	assertPhase(phase);
+	const current = nextPhase(state);
+	if (!(current === "execute" && phase === "plan" || current === "look_back" && (phase === "execute" || phase === "plan"))) throw new Error(`transition from "${current ?? "complete"}" to "${phase}" is not allowed`);
+	return {
+		...state,
+		completed: PHASES.slice(0, PHASES.indexOf(phase))
+	};
+}
+/** Render a compact current-state block for the runtime context snapshot. */
+function renderWorkflowStatus(state) {
+	const complete = isWorkflowComplete(state);
+	const completed = state.completed.length === 0 ? "(none)" : state.completed.map((phase) => PHASE_TITLES[phase]).join(" -> ");
+	const current = nextPhase(state);
+	return [
+		complete ? "Research workflow complete:" : "Active research workflow:",
+		`Problem: ${state.problem}`,
+		`Completed phases: ${completed}`,
+		complete ? "Status: complete" : `Next required phase: ${PHASE_TITLES[current]}`
+	].join("\n");
+}
+//#endregion
+//#region src/index.ts
+const name = "researchly";
+const inject = ["tools", "systemPrompt"];
+const TOOL_NAME = "research_workflow";
+const WORKFLOW_SUMMARY = `# Research workflow
+
+You are solving a mathematical or physical research problem. Work through the following four phases in order. Present a final solution after the workflow status reports that all four phases are complete:
+
+1. Understanding the problem
+2. Devising a plan
+3. Carrying out, checking, and revising
+4. Looking back
+
+The runtime context provides the detailed instructions for whichever phase is currently active.
+
+- Use the available tools appropriate to each phase: search or read references, run symbolic or numerical computations, inspect files, and query the web.
+
+## Workflow tool protocol
+
+- Call \`${TOOL_NAME}\` with action \`start\` before working on a research problem.
+- Call action \`phase_complete\` with the current \`phase\` only after it is genuinely finished, in the order: understand, plan, execute, look_back.
+- If execution is obstructed, call action \`reopen\` with phase \`plan\` before revising the plan.
+- If a check fails, call action \`reopen\` with phase \`execute\` for problems within the existing plan, or \`plan\` for problems with the plan itself. Explain the cause in your response. Do not mark the failed phase complete.
+- After reopening a phase, complete it and the following phases again, including looking back. Use \`reopen\` rather than restarting the problem.
+- Call action \`status\` whenever you need to see the current workflow state.
+- Use action \`abandon\` only when the user explicitly stops the problem.`;
+function isRootAgent(agent) {
+	return agent.session.header.origin !== "subagent";
+}
+function completedPhases(state) {
+	return [...state.completed];
+}
+function remainingPhases(state) {
+	return PHASES.filter((phase) => !state.completed.includes(phase));
+}
+function resultFor(message, state, active = state !== void 0 && !isWorkflowComplete(state)) {
+	return {
+		message,
+		active,
+		...state === void 0 ? {} : { problem: state.problem },
+		completed: state === void 0 ? [] : completedPhases(state),
+		remaining: state === void 0 ? [...PHASES] : remainingPhases(state)
+	};
+}
+function requireActive(workflows, agent) {
+	const state = workflows.get(agent.id);
+	if (state === void 0) throw new Error(`no active research workflow; call ${TOOL_NAME} with action "start" first`);
+	if (isWorkflowComplete(state)) throw new Error(`this research workflow is already complete; call ${TOOL_NAME} with action "start" to begin a new problem`);
+	return state;
+}
+function requirePhase(value) {
+	if (typeof value !== "string" || !PHASES.includes(value)) throw new Error(`phase must be one of: ${PHASES.join(", ")}`);
+	return value;
+}
+function apply(ctx) {
+	const workflows = /* @__PURE__ */ new Map();
+	ctx.systemPrompt.section({
+		name: "research:workflow",
+		order: ctx.systemPrompt.getSectionOrder("PLAN_POLICY") + 10,
+		text: `Use \`research_workflow\` only when at least one of the following is true:
+    1. User explicitly asks to use it. In that case, call \`research_workflow\` with action "start". 2. The task is obviously beyond ordinary textbook exercise level: solving it requires a non-standard method, several connected steps, resolving ambiguous definitions/conventions, or checking the result through non-trivial limits. 3. The task has a real research background: it asks you to verify, apply, or extend a result from a paper/research context, or it's part of an ongoing research project.
+    Do NOT use this tool for ordinary exercise-level work such as a direct integral, easy simplification/substitution, standard equation, or a textbook proof whose method is already clear.`
+	});
+	ctx.systemPrompt.context({
+		name: "research:workflow-status",
+		order: ctx.systemPrompt.getContextOrder("SUBAGENT_DELEGATION") + 10,
+		text: (context) => {
+			const agent = context.agent;
+			if (agent === void 0 || !isRootAgent(agent)) return "";
+			const state = workflows.get(agent.id);
+			if (state === void 0) return "";
+			const status = renderWorkflowStatus(state);
+			const phase = nextPhase(state);
+			const guidance = phase === void 0 ? status : `${status}\n\n${PHASE_GUIDANCE[phase]}`;
+			return `${WORKFLOW_SUMMARY}\n\n${guidance}`;
+		}
+	});
+	ctx.on("agent/disposed", ({ agent }) => {
+		workflows.delete(agent.id);
+	});
+	ctx.on("agent/turn-stopping", ({ agent }) => {
+		if (!isRootAgent(agent)) return;
+		const state = workflows.get(agent.id);
+		if (state === void 0 || isWorkflowComplete(state)) return;
+		const phase = nextPhase(state);
+		if (phase === void 0) return;
+		agent.steer({
+			content: [{
+				type: "text",
+				text: `The research workflow is still active. Work on "${PHASE_TITLES[phase]}" and call ${TOOL_NAME} with action "phase_complete" only when it is finished. If execution is obstructed, reopen "plan"; if a check fails, reopen "execute" or "plan" according to the cause. Do not mark a failed phase complete. Use action "abandon" only if the user has explicitly stopped this problem.`
+			}],
+			source: {
+				kind: "plugin",
+				plugin: name
+			}
+		});
+	});
+	ctx.tools.register(defineTool({
+		name: TOOL_NAME,
+		description: `Guide a four-phase research workflow. Call start, then complete phases in order: understand, plan, execute, look_back. Use reopen to return from execute to plan, or from look_back to execute or plan. Use status to inspect progress, and abandon only when the user explicitly stops the problem.`,
+		parameters: {
+			action: {
+				type: "string",
+				required: true,
+				enum: [
+					"start",
+					"status",
+					"phase_complete",
+					"reopen",
+					"abandon"
+				],
+				description: "The workflow action to perform."
+			},
+			problem: {
+				type: "string",
+				description: "Required for action \"start\": the research problem to solve."
+			},
+			phase: {
+				type: "string",
+				enum: [...PHASES],
+				description: "Required for \"phase_complete\": the current phase. Required for \"reopen\": the earlier phase to return to (plan or execute)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					message: {
+						type: "string",
+						required: true
+					},
+					active: {
+						type: "boolean",
+						required: true
+					},
+					problem: { type: "string" },
+					completed: {
+						type: "array",
+						required: true,
+						items: { type: "string" }
+					},
+					remaining: {
+						type: "array",
+						required: true,
+						items: { type: "string" }
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.message
+			}]
+		},
+		async execute(args, exec) {
+			const agent = exec.agent;
+			if (agent === void 0) throw new Error(`${TOOL_NAME} requires a calling agent`);
+			if (!isRootAgent(agent)) throw new Error(`${TOOL_NAME} is only available to the root researcher; subagents should work on focused delegated subtasks`);
+			const action = args.action;
+			if (action === "start") {
+				if (typeof args.problem !== "string") throw new Error("action \"start\" requires a non-empty problem");
+				const previous = workflows.get(agent.id);
+				if (previous !== void 0 && !isWorkflowComplete(previous)) throw new Error("a research workflow is already active; call status first, or abandon it explicitly");
+				const state = startWorkflow(args.problem);
+				workflows.set(agent.id, state);
+				return resultFor("Research workflow started. Complete the phases in order: understand, plan, execute, look_back.", state, true);
+			}
+			if (action === "status") {
+				const state = workflows.get(agent.id);
+				if (state === void 0) return resultFor("No active research workflow.", void 0, false);
+				const complete = isWorkflowComplete(state);
+				return resultFor(complete ? "Research workflow is complete." : `Active research workflow. Next required phase: ${nextPhase(state)}.`, state, !complete);
+			}
+			if (action === "abandon") return resultFor(workflows.delete(agent.id) ? "Research workflow abandoned." : "No active research workflow to abandon.", void 0, false);
+			const state = requireActive(workflows, agent);
+			if (action === "reopen") {
+				const phase = requirePhase(args.phase);
+				const next = reopenWorkflowPhase(state, phase);
+				workflows.set(agent.id, next);
+				return resultFor(`Returned to phase "${phase}". Complete this phase and all following phases again.`, next, true);
+			}
+			if (action === "phase_complete") {
+				const phase = requirePhase(args.phase);
+				const next = completeWorkflowPhase(state, phase);
+				workflows.set(agent.id, next);
+				if (isWorkflowComplete(next)) return resultFor("All four research phases are complete. You may now present the final answer after looking back over the result.", next, false);
+				return resultFor(`Phase "${phase}" complete. Next required phase: ${nextPhase(next)}.`, next, true);
+			}
+			throw new Error(`unsupported workflow action: ${String(action)}`);
+		}
+	}));
+}
+//#endregion
+export { apply, inject, name };

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "dsh-researchly",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "packageManager": "pnpm@11.28.5",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": "./lib/index.js",
+  "files": ["lib", "cordis.yml"],
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": "^0.2.2-rc.1"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsdown --config-loader native",
+    "prepare": "pnpm run build",
+    "test": "node --experimental-transform-types --test --test-isolation=none src/*.test.ts",
+    "test:state": "node --experimental-strip-types --test --test-isolation=none src/state.test.ts"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0",
+    "@deepseek-ai/dsh-agent": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.2-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.1.0",
+    "@deepseek-ai/dsh-agent": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.2.2-rc.1",
+    "tsdown": "0.22.2"
+  },
+  "license": "MIT"
+}