remote-project-control

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Remote Project Control

远程项目控制

Help the user operate a project whose code is edited locally but actually runs on one or more remote servers over SSH. Establish project memory first, then coordinate safe local and remote actions.

Pair this skill with

research-project-memory

when remote execution state should be linked to project-level experiments, evidence, actions, or worktree status.

帮助用户操作代码在本地编辑但实际通过SSH在一台或多台远程服务器上运行的项目。首先建立项目记忆，再协调安全的本地和远程操作。

当远程执行状态需要与项目级实验、证据、操作或工作树状态关联时，请将此技能与

research-project-memory

结合使用。

Skill Directory Layout

技能目录结构

text

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── memory-model.md
│   └── operations.md
├── template_manifest.json
└── templates/
    ├── infra/remote-projects.yaml
    ├── docs/ops/current-status.md
    ├── docs/ops/decision-log.md
    └── agent/local-overrides.yaml

text

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── memory-model.md
│   └── operations.md
├── template_manifest.json
└── templates/
    ├── infra/remote-projects.yaml
    ├── docs/ops/current-status.md
    ├── docs/ops/decision-log.md
    └── agent/local-overrides.yaml

Progressive Loading

渐进式加载

Always read
```
references/memory-model.md
```
Read
```
references/operations.md
```
when the user wants to inspect, sync, run, monitor, or fetch artifacts
Use
```
templates/
```
as the source of truth when bootstrapping memory files into the target project
If the repo has
```
memory/
```
, summarize verified remote execution facts into
```
research-project-memory
```
boards without duplicating the remote manifest.

务必读取
```
references/memory-model.md
```
当用户想要检查、同步、运行、监控或获取工件时，读取
```
references/operations.md
```
在将记忆文件引导到目标项目时，以
```
templates/
```
作为事实来源
如果仓库包含
```
memory/
```
，将已验证的远程执行事实汇总到
```
research-project-memory
```
看板中，不要重复远程清单内容。

Core Principles

核心原则

Memory is bootstrap context, not execution truth
Stable shared facts belong in the repo; private machine-specific facts belong in a local override file
Verify volatile state before acting on it
Prefer GitHub or the configured git remote for code sync; do not improvise ad hoc source copying unless the project explicitly uses it
Never use destructive remote git commands without explicit user approval

记忆是引导上下文，而非执行事实
稳定的共享事实应存放在仓库中；私有机器特定事实应存放在本地覆盖文件中
在执行操作前验证易失性状态
优先使用GitHub或配置的git远程仓库进行代码同步；除非项目明确使用，否则不要临时即兴复制源代码
未经用户明确批准，切勿使用破坏性的远程git命令

Memory Files

记忆文件

This skill manages four project-memory files with distinct roles:

```
infra/remote-projects.yaml
```
: stable shared facts such as local/remote repo mapping, scheduler type, launch modes, key paths, and safety policies
```
docs/ops/current-status.md
```
: working memory for the current phase of the project, including active branch, focus, latest known job, open issues, and next step
```
docs/ops/decision-log.md
```
: durable explanations for why stable workflow decisions were made
```
.agent/local-overrides.yaml
```
: optional private overrides for one user's machine, ssh aliases, usernames, and private paths; this file should usually be gitignored

If one or more files are missing, bootstrap them from the bundled templates before trying to infer project context from scratch.

此技能管理四个具有不同作用的项目记忆文件：

```
infra/remote-projects.yaml
```
：稳定的共享事实，例如本地/远程仓库映射、调度器类型、启动模式、关键路径和安全策略
```
docs/ops/current-status.md
```
：项目当前阶段的工作记忆，包括活跃分支、重点任务、最新已知作业、未解决问题和下一步计划
```
docs/ops/decision-log.md
```
：对稳定工作流决策原因的持久化说明
```
.agent/local-overrides.yaml
```
：针对单个用户机器的可选私有覆盖配置，包括SSH别名、用户名和私有路径；此文件通常应被git忽略

如果缺少一个或多个文件，请先使用此技能中的模板引导生成这些文件，再尝试从头推断项目上下文。

Step 1 — Orient and Load Memory

步骤1 — 定位并加载记忆

Detect the project root:

bash

git rev-parse --show-toplevel 2>/dev/null || pwd

Read the existing memory files if present:

<project-root>/infra/remote-projects.yaml

<project-root>/docs/ops/current-status.md

<project-root>/.agent/local-overrides.yaml

```
<project-root>/docs/ops/decision-log.md
```

If
```
infra/remote-projects.yaml
```
is missing, bootstrap the project memory using the templates in this skill. Ask only for the minimum critical fields:

project name
local repo root
default server name
ssh alias
remote repo root
scheduler type
default launch mode
environment activation command

If
```
.agent/local-overrides.yaml
```
is missing but private overrides are clearly needed, offer to create it and recommend adding
```
.agent/
```
to
```
.gitignore
```
.

bash

git rev-parse --show-toplevel 2>/dev/null || pwd

如果存在，读取现有记忆文件：

<project-root>/infra/remote-projects.yaml

<project-root>/docs/ops/current-status.md

<project-root>/.agent/local-overrides.yaml

```
<project-root>/docs/ops/decision-log.md
```

如果
```
infra/remote-projects.yaml
```
缺失，使用此技能中的模板引导生成项目记忆。仅询问最关键的必填字段：

项目名称
本地仓库根目录
默认服务器名称
SSH别名
远程仓库根目录
调度器类型
默认启动模式
环境激活命令

如果
```
.agent/local-overrides.yaml
```
缺失但明显需要私有覆盖配置，主动提出创建该文件并建议将
```
.agent/
```
添加到
```
.gitignore
```
中。

Step 2 — Build the Session Bootstrap Summary

步骤2 — 生成会话引导摘要

Merge the loaded files into a concise project context summary. Always show the user a compact bootstrap summary before doing substantial remote work.

Include, when known:

project name
local repo root, current branch, short commit, and whether the tree is dirty
default remote server and remote repo root
scheduler type and default launch mode
environment activation command
key data, checkpoint, scratch, and logs roots
current focus
latest known job
open issues
next planned step
any missing required fields

将加载的文件合并为简洁的项目上下文摘要。在进行大量远程工作前，务必向用户展示一份紧凑的引导摘要。

已知信息需包含：

项目名称
本地仓库根目录、当前分支、短提交哈希，以及工作树是否有未提交更改
默认远程服务器和远程仓库根目录
调度器类型和默认启动模式
环境激活命令
关键数据、检查点、临时文件和日志的根目录
当前重点任务
最新已知作业
未解决问题
计划的下一步操作
任何缺失的必填字段

Step 3 — Re-validate Volatile State Before Action

步骤3 — 执行操作前重新验证易失性状态

Before any remote action, verify the pieces of state that could have changed since the last session.

At minimum:

bash

git rev-parse --short HEAD
git branch --show-current
git status --short

For the chosen remote server, verify the remote repo and git state using the configured

ssh_alias

and

remote_repo_root

bash

ssh <ssh-alias> "cd <remote-repo-root> && pwd && git branch --show-current && git rev-parse --short HEAD && git status --short"

If the request involves job submission or monitoring, also verify the scheduler tool and relevant log or output paths on the remote host.

在执行任何远程操作前，验证自上次会话以来可能已更改的状态信息。

至少执行以下验证：

bash

git rev-parse --short HEAD
git branch --show-current
git status --short

对于选定的远程服务器，使用配置的

ssh_alias

和

remote_repo_root

验证远程仓库和git状态：

bash

ssh <ssh-alias> "cd <remote-repo-root> && pwd && git branch --show-current && git rev-parse --short HEAD && git status --short"

如果请求涉及任务提交或监控，还需验证远程主机上的调度器工具以及相关日志或输出路径。

Step 4 — Classify the Request and Execute

步骤4 — 分类请求并执行

Choose one of the following flows and follow the detailed guidance in

references/operations.md

```
bootstrap
```
: create or repair the memory files from templates and fill the minimum required fields
```
inspect
```
: compare local and remote git state, verify paths, env activation, scheduler availability, and summarize the current situation
```
sync-code
```
: prepare local commits, push through the configured git remote, and update the remote repo with non-destructive fast-forward pulls only
```
run-job
```
: use the remote context to submit a job safely; if a new reproducible job script is needed, use
```
run-experiment
```
after this skill has established the environment
```
interactive-session
```
: prepare the correct
```
salloc
```
,
```
srun
```
, or equivalent command and run subsequent commands from the remote repo with the configured environment activation
```
monitor
```
: inspect queue state and tail logs from the configured log roots
```
artifacts
```
: locate remote checkpoints, outputs, and logs; do not bulk-transfer large data unless the user explicitly asks
```
closeout
```
: update project memory at the end of a session

If the runtime cannot execute SSH commands directly, still use this skill: generate the exact commands in the correct order, explain the assumptions, and keep the memory files up to date.

选择以下流程之一，并遵循

references/operations.md

中的详细指引：

```
bootstrap
```
：从模板创建或修复记忆文件，并填写最少必填字段
```
inspect
```
：比较本地和远程git状态，验证路径、环境激活、调度器可用性，并总结当前情况
```
sync-code
```
：准备本地提交，通过配置的git远程仓库推送，仅使用非破坏性的快进拉取更新远程仓库
```
run-job
```
：使用远程上下文安全提交任务；如果需要新的可复现任务脚本，在本技能完成环境配置后使用
```
run-experiment
```
```
interactive-session
```
：准备正确的
```
salloc
```
、
```
srun
```
或等效命令，并从远程仓库运行后续命令，同时激活配置的环境
```
monitor
```
：检查队列状态，并从配置的日志根目录跟踪日志
```
artifacts
```
：定位远程检查点、输出和日志；除非用户明确要求，否则不要批量传输大型数据
```
closeout
```
：在会话结束时更新项目记忆

如果运行时无法直接执行SSH命令，仍可使用此技能：生成正确顺序的精确命令，说明假设前提，并保持记忆文件更新。

Step 5 — Write Back to the Right Memory Layer

步骤5 — 写入正确的记忆层

When new information becomes trustworthy, persist it to the appropriate file:

stable mapping and policy changes ->
```
infra/remote-projects.yaml
```
current branch, latest known job, current focus, blockers, and next step ->
```
docs/ops/current-status.md
```
durable workflow rationale ->
```
docs/ops/decision-log.md
```
user-specific ssh aliases, usernames, and private paths ->
```
.agent/local-overrides.yaml
```

If the repo also uses

research-project-memory

, write only cross-project pointers:

```
memory/evidence-board.md
```
: verified job/run pointer for linked
```
EXP-###
```
```
memory/action-board.md
```
: monitor, fetch-artifact, rerun, or report actions
```
memory/current-status.md
```
: latest verified remote execution summary and next verification step
worktree
```
.agent/worktree-status.md
```
: remote run status when tied to a branch/worktree purpose

Do not write volatile scheduler output or one-off shell command results into the stable manifest.

当新信息可靠时，将其持久化到相应文件：

稳定映射和策略变更 ->
```
infra/remote-projects.yaml
```
当前分支、最新已知作业、当前重点任务、障碍和下一步操作 ->
```
docs/ops/current-status.md
```
持久化工作流原理 ->
```
docs/ops/decision-log.md
```
用户特定的SSH别名、用户名和私有路径 ->
```
.agent/local-overrides.yaml
```

如果仓库同时使用

research-project-memory

，仅写入跨项目指针：

```
memory/evidence-board.md
```
：关联
```
EXP-###
```
的已验证作业/运行指针
```
memory/action-board.md
```
：监控、获取工件、重新运行或报告操作
```
memory/current-status.md
```
：最新已验证的远程执行摘要和下一步验证步骤
工作树
```
.agent/worktree-status.md
```
：与分支/工作树用途关联的远程运行状态

不要将易失性调度器输出或一次性shell命令结果写入稳定清单。

Step 6 — End Every Substantial Session with Closeout

步骤6 — 所有重要会话结束时执行收尾操作

Before finishing, update

docs/ops/current-status.md

whenever the session materially changed project state. Capture:

branch or commit the user should resume from
what was changed locally
what was synced to the remote repo
latest known submitted or running job
log or output paths worth checking next
the next concrete action for the next session

If a new stable practice was established, add a short entry to

docs/ops/decision-log.md

If the project has

memory/current-status.md

, update it with a concise cross-component pointer rather than copying the full remote status.

在结束前，只要会话实质性改变了项目状态，就更新

docs/ops/current-status.md

。记录以下内容：

用户后续应从中恢复的分支或提交
本地已更改的内容
已同步到远程仓库的内容
最新已知的已提交或运行中的作业
下次值得检查的日志或输出路径
下一次会话的具体操作

如果建立了新的稳定实践，在

docs/ops/decision-log.md

中添加简短条目。

如果项目包含

memory/current-status.md

，仅用简洁的跨组件指针更新它，不要复制完整的远程状态。

Bootstrap Targets

引导目标

When bootstrapping a project, materialize these files from

templates/

templates/infra/remote-projects.yaml

<project-root>/infra/remote-projects.yaml

templates/docs/ops/current-status.md

<project-root>/docs/ops/current-status.md

templates/docs/ops/decision-log.md

<project-root>/docs/ops/decision-log.md

templates/agent/local-overrides.yaml

<project-root>/.agent/local-overrides.yaml

when private overrides are needed

Preserve existing files unless the user explicitly asks to overwrite them.

引导项目时，从

templates/

生成以下文件：

templates/infra/remote-projects.yaml

<project-root>/infra/remote-projects.yaml

templates/docs/ops/current-status.md

<project-root>/docs/ops/current-status.md

templates/docs/ops/decision-log.md

<project-root>/docs/ops/decision-log.md

当需要私有覆盖配置时，

templates/agent/local-overrides.yaml

<project-root>/.agent/local-overrides.yaml

除非用户明确要求覆盖，否则保留现有文件。